Skip to main content
Product groups define which products belong together and how customers can switch between them. This enables self-service upgrades and downgrades in the customer portal.
Product groups differ from product families: While product families are only for organizing the catalog, product groups control the switching options between products.

​
Use Cases

ScenarioDescription
Tier ChangeCustomer switches from Starter to Pro package
UpgradeCustomer books a higher-value package
DowngradeCustomer switches to a cheaper package
Quantity ChangeCustomer changes the number of licenses

​
Concept

A product group consists of multiple tiers, each representing a product with its price plans. The order of tiers determines the upgrade/downgrade direction. 
Product Group: "SaaS Packages"
├── Position 1: Starter (cheapest)
├── Position 2: Pro
└── Position 3: Enterprise (most expensive)
  • Upgrade: Switch to a higher position (e.g., Starter → Pro)
  • Downgrade: Switch to a lower position (e.g., Pro → Starter)

​
Create Product Group

1

Create Product Group

Navigate to Products > Product Groups and click “Create Product Group”.Assign a name like “SaaS Packages” or “Hosting Plans”.
2

Add Tiers

Add a tier for each package:
  1. Select the Product (e.g., “Starter Plan”)
  2. Select the Price Plans (e.g., “Starter Monthly”, “Starter Yearly”)
  3. Configure Upgrade/Downgrade behavior
3

Set Order

Arrange tiers in the desired order. The position determines what counts as upgrade or downgrade.

​
Tier Settings

Each tier in a product group has the following settings:

​
Upgrade & Downgrade

SettingDescription
UpgradeableCan switch to higher positions
DowngradeableCan switch to lower positions
The cheapest package should have upgradeable: true, downgradeable: false since there’s no lower package.

​
Change Timing

OptionDescription
Immediately (immediately)Change becomes active immediately
End of Period (end_of_period)Change becomes active at end of current billing period

​
Credit Type

Only relevant when changeTiming = immediately:
OptionDescription
Pro Rata (pro_rata)Credit based on remaining days
Full (full)Full credit of current period
Last Invoiced (last_invoiced)Credit of last invoice
None (none)No credit

​
Assign Product Group

For customers to be able to switch, the product group must be assigned to a subscription item.
Automatic Assignment in Checkout: When a price plan is linked to a product group, the product group is automatically assigned to subscriptions created via checkout. Manual assignment is only required for subscriptions created in the wallet.
1

Open Subscription

Navigate to the subscription and open the item for which upgrades/downgrades should be enabled.
2

Assign Product Group

Under “Product Group”, select the appropriate group.

​
Perform Switch

​
In Customer Portal

Once a product group is assigned, customers see available switch options in the customer portal:
  1. Customer opens their subscription
  2. Clicks “Change”
  3. Selects new package and confirms
  4. Change is applied immediately or at period end based on configuration

​
Via API

# 1. Get available options
curl -X GET "https://coreapi.io/subscription-items/{itemId}/change-options" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Apply change
curl -X POST "https://coreapi.io/product-group-memberships/{tierId}/apply" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subscriptionItem": "item-uuid",
    "selectedPricePlan": "price-plan-uuid",
    "quantity": 1
  }'

​
Settings

​
Force Same Billing Interval

With forceSameBillingInterval: true, customers can only switch between price plans with the same billing interval. A customer with a monthly plan will only see monthly options.

​
API Overview

EndpointMethodDescription
/catalogue/product-groupsGETGet all product groups
/catalogue/product-groupsPOSTCreate new product group
/catalogue/product-groups/{id}GETGet single product group
/catalogue/product-groups/{id}PUTUpdate product group
/catalogue/product-groups/{id}DELETEDelete product group
/subscription-items/{id}/product-groupPUTEnable up- & downgrades
/subscription-items/{id}/change-optionsGETGet available switch options
/product-group-memberships/{id}/applyPOSTChange tier

Subscription Transitions

Manual transitions with proration

Products

Create and manage products

Customer Portal

Self-service for customers

API Guide: Upgrades

Integrate upgrades into your apps