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

# Subscription migration methods

When moving a customer from one plan type to another, Stigg uses one of two migration mechanisms:

* **Provision new subscription**: Creates a brand new subscription. Required when the target plan requires billable metric values or variable entitlement values.
* **Migrate subscription to latest version**: Updates the existing subscription in place to match the latest version of the target plan.

## Migration Matrix

| Path              | Migration Type                             | Notes                                                                                                                                                                                                                    |
| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Free → Paid**   | **Provision new subscription**             | A new subscription must be created because paid plans require billable metric values.                                                                                                                                    |
| **Free → Custom** | **Provision new subscription**             | A new subscription must be created because custom plans require values for variable entitlements.                                                                                                                        |
| **Paid → Free**   | **Migrate subscription to latest version** | The existing subscription is migrated to the latest free plan version.                                                                                                                                                   |
| **Paid → Custom** | **Migrate subscription to latest version** | The subscription is migrated in place. **Important:** The existing subscription in the external billing system is *not* canceled. Only Stigg-related metadata (such as `stiggEntityId` and `stiggEntityUrl`) is removed. |
| **Custom → Paid** | **Provision new subscription**             | A new subscription must be created because paid plans require billable metric values.                                                                                                                                    |
| **Custom → Free** | **Migrate subscription to latest version** | The existing subscription is migrated to the latest free plan version.                                                                                                                                                   |