Upgrades & Downgrades

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

Scenario	Description
Tier Change	Customer switches from Starter to Pro package
Upgrade	Customer books a higher-value package
Downgrade	Customer switches to a cheaper package
Quantity Change	Customer 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

Using Web App
Using API

Create Product Group

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

Add Tiers

Add a tier for each package:

Select the Product (e.g., “Starter Plan”)
Select the Price Plans (e.g., “Starter Monthly”, “Starter Yearly”)
Configure Upgrade/Downgrade behavior

Set Order

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

curl -X POST "https://coreapi.io/catalogue/product-groups" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "SaaS Packages",
    "enabled": true,
    "forceSameBillingInterval": false,
    "tiers": [
      {
        "product": "/products/starter-uuid",
        "pricePlans": ["/plans/starter-monthly-uuid"],
        "position": 1,
        "upgradeable": true,
        "downgradeable": false,
        "changeTiming": "end_of_period",
        "label": "Starter"
      },
      {
        "product": "/products/pro-uuid",
        "pricePlans": ["/plans/pro-monthly-uuid"],
        "position": 2,
        "upgradeable": true,
        "downgradeable": true,
        "changeTiming": "immediately",
        "creditType": "pro_rata",
        "label": "Pro"
      }
    ]
  }'

Tier Settings

Each tier in a product group has the following settings:

Upgrade & Downgrade

Setting	Description
Upgradeable	Can switch to higher positions
Downgradeable	Can switch to lower positions

The cheapest package should have upgradeable: true, downgradeable: false since there’s no lower package.

Change Timing

Option	Description
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:

Option	Description
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.

Using Web App
Using API

Open Subscription

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

Assign Product Group

Under “Product Group”, select the appropriate group.

curl -X PUT "https://coreapi.io/subscription-items/{itemId}/product-group" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "productGroupMembership": "tier-uuid"
  }'

Perform Switch

In Customer Portal

Once a product group is assigned, customers see available switch options in the customer portal:

Customer opens their subscription
Clicks “Change”
Selects new package and confirms
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

Endpoint	Method	Description
`/catalogue/product-groups`	GET	Get all product groups
`/catalogue/product-groups`	POST	Create new product group
`/catalogue/product-groups/{id}`	GET	Get single product group
`/catalogue/product-groups/{id}`	PUT	Update product group
`/catalogue/product-groups/{id}`	DELETE	Delete product group
`/subscription-items/{id}/product-group`	PUT	Enable up- & downgrades
`/subscription-items/{id}/change-options`	GET	Get available switch options
`/product-group-memberships/{id}/apply`	POST	Change 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

Getting Started

Customers

Products

Usage-Based Billing

Subscriptions

Invoices

Payments

Analytics

AI Assistant

Lists & Filters

Settings

Notifications

Accounting

Developers

Upgrades & Downgrades

Use Cases

Concept

Create Product Group

Tier Settings

Upgrade & Downgrade

Change Timing

Credit Type

Assign Product Group

Perform Switch

In Customer Portal

Via API

Settings

Force Same Billing Interval

API Overview

Subscription Transitions

Products

Customer Portal

API Guide: Upgrades

​Use Cases

​Concept

​Create Product Group

​Tier Settings

​Upgrade & Downgrade

​Change Timing

​Credit Type

​Assign Product Group

​Perform Switch

​In Customer Portal

​Via API

​Settings

​Force Same Billing Interval

​API Overview

​Related Documentation

Subscription Transitions

Products

Customer Portal

API Guide: Upgrades

Use Cases

Concept

Create Product Group

Tier Settings

Upgrade & Downgrade

Change Timing

Credit Type

Assign Product Group

Perform Switch

In Customer Portal

Via API

Settings

Force Same Billing Interval

API Overview

Related Documentation