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.