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.