> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrades & Downgrades

> Define upgrade and downgrade paths for self-service package changes

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.

<Note>
  Product groups differ from product families: While product families are only for organizing the catalog, product groups control the switching options between products.
</Note>

## 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

<Tabs>
  <Tab title="Using Web App">
    <Steps>
      <Step title="Create Product Group">
        Navigate to **Products > Product Groups** and click "Create Product Group".

        Assign a name like "SaaS Packages" or "Hosting Plans".
      </Step>

      <Step title="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**
      </Step>

      <Step title="Set Order">
        Arrange tiers in the desired order. The position determines what counts as upgrade or downgrade.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Using API">
    ```bash theme={null}
    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"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

***

## 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  |

<Tip>
  The cheapest package should have `upgradeable: true, downgradeable: false` since there's no lower package.
</Tip>

### 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.

<Tip>
  **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.
</Tip>

<Tabs>
  <Tab title="Using Web App">
    <Steps>
      <Step title="Open Subscription">
        Navigate to the subscription and open the item for which upgrades/downgrades should be enabled.
      </Step>

      <Step title="Assign Product Group">
        Under "Product Group", select the appropriate group.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Using API">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

***

## 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

```bash theme={null}
# 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`](/api-reference/productgroup/get-product-groups)                | GET    | Get all product groups       |
| [`/catalogue/product-groups`](/api-reference/productgroup/create-product-group)              | POST   | Create new product group     |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/get-product-group)            | GET    | Get single product group     |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/update-product-group)         | PUT    | Update product group         |
| [`/catalogue/product-groups/{id}`](/api-reference/productgroup/delete-product-group)         | DELETE | Delete product group         |
| [`/subscription-items/{id}/product-group`](/api-reference/productgroup/assign-product-group) | PUT    | Enable up- & downgrades      |
| [`/subscription-items/{id}/change-options`](/api-reference/productgroup/get-change-options)  | GET    | Get available switch options |
| [`/product-group-memberships/{id}/apply`](/api-reference/productgroup/apply-membership)      | POST   | Change tier                  |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Subscription Transitions" icon="arrow-right-arrow-left" href="/guide/subscriptions/transitions">
    Manual transitions with proration
  </Card>

  <Card title="Products" icon="box" href="/guide/catalogue/products">
    Create and manage products
  </Card>

  <Card title="Customer Portal" icon="user" href="/guide/customers/customer-portal">
    Self-service for customers
  </Card>

  <Card title="API Guide: Upgrades" icon="code" href="/api-reference/guides/implement-upgrades">
    Integrate upgrades into your apps
  </Card>
</CardGroup>