> ## 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. # Migrate subscription to latest plan version > Migrates a subscription to the latest published version of its plan or add-ons. Handles prorated charges or credits automatically. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/stigg/openapi.documented.yml post /api/v1/subscriptions/{id}/migrate openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.93.1 contact: {} servers: - url: https://api.stigg.io description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Operations related to customers - name: Subscriptions description: Operations related to subscriptions - name: Coupons description: Operations related to coupons - name: Bulk Import description: Operations related to import of customers and subscriptions - name: Usage description: Operations related to usage & metering - name: Promotional Entitlements description: Operations related to promotional entitlements - name: Products description: Operations related to products - name: Features description: Operations related to features - name: Addons description: Operations related to addons - name: Plans description: Operations related to plans - name: Credit grants description: Operations related to credit grants - name: Credit ledger description: Operations related to credit ledger - name: Custom currencies description: Operations related to custom currencies paths: /api/v1/subscriptions/{id}/migrate: post: tags: - Subscriptions summary: Migrate subscription to latest plan version description: >- Migrates a subscription to the latest published version of its plan or add-ons. Handles prorated charges or credits automatically. operationId: SubscriptionController_migrateSubscription parameters: - name: id required: true in: path description: The unique identifier of the entity schema: minLength: 1 maxLength: 255 type: string - name: X-ACCOUNT-ID in: header description: >- Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth. required: false schema: type: string - name: X-ENVIRONMENT-ID in: header description: >- Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key). required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MigrateSubscriptionRequestDto' responses: '200': description: The migrated subscription object. content: application/json: schema: $ref: '#/components/schemas/SubscriptionResponseDto' '400': description: bad request. content: application/json: schema: $ref: '#/components/schemas/BadInputErrorResponseDto' '401': description: User is not authenticated. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponseDto' '403': description: User is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponseDto' '404': description: Subscription not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' x-codeSamples: - lang: JavaScript source: |- import Stigg from '@stigg/typescript'; const client = new Stigg({ apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted }); const subscription = await client.v1.subscriptions.migrate('x'); console.log(subscription.data); - lang: Python source: |- import os from stigg import Stigg client = Stigg( api_key=os.environ.get("STIGG_API_KEY"), # This is the default and can be omitted ) subscription = client.v1.subscriptions.migrate( id="x", ) print(subscription.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stiggio/stigg-go\"\n\t\"github.com/stiggio/stigg-go/option\"\n)\n\nfunc main() {\n\tclient := stigg.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tsubscription, err := client.V1.Subscriptions.Migrate(\n\t\tcontext.TODO(),\n\t\t\"x\",\n\t\tstigg.V1SubscriptionMigrateParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", subscription.Data)\n}\n" - lang: Java source: |- package io.stigg.example; import io.stigg.client.StiggClient; import io.stigg.client.okhttp.StiggOkHttpClient; import io.stigg.models.v1.subscriptions.Subscription; import io.stigg.models.v1.subscriptions.SubscriptionMigrateParams; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); Subscription subscription = client.v1().subscriptions().migrate("x"); } } - lang: Ruby source: |- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") subscription = stigg.v1.subscriptions.migrate("x") puts(subscription) - lang: C# source: >- using System; using Stigg.Client; using Stigg.Client.Models.V1.Subscriptions; StiggClient client = new(); SubscriptionMigrateParams parameters = new() { ID = "x" }; var subscription = await client.V1.Subscriptions.Migrate(parameters); Console.WriteLine(subscription); - lang: CLI source: |- stigg v1:subscriptions migrate \ --api-key 'My API Key' \ --id x components: schemas: MigrateSubscriptionRequestDto: type: object properties: subscriptionMigrationTime: type: string enum: - END_OF_BILLING_PERIOD - IMMEDIATE description: When to migrate (immediate or period end) additionalProperties: false title: MigrateSubscriptionRequest description: >- Migrate a subscription to the latest version of its plan or add-on. This updates pricing, entitlements, and features to match the currently published version while maintaining the subscription continuity. SubscriptionResponseDto: type: object properties: data: type: object properties: id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Subscription ID customerId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Customer ID payingCustomerId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Paying customer ID for delegated billing nullable: true resourceId: type: string maxLength: 255 description: Resource ID nullable: true billingId: type: string maxLength: 255 description: Billing ID nullable: true createdAt: type: string format: date-time description: Created at startDate: type: string format: date-time description: Subscription start date endDate: type: string format: date-time description: Subscription end date nullable: true effectiveEndDate: type: string format: date-time description: Subscription effective end date nullable: true cancellationDate: type: string format: date-time description: Subscription cancellation date nullable: true trialEndDate: type: string format: date-time description: Subscription trial end date nullable: true status: type: string enum: - PAYMENT_PENDING - ACTIVE - EXPIRED - IN_TRIAL - CANCELED - NOT_STARTED description: Subscription status cancelReason: type: string enum: - UPGRADE_OR_DOWNGRADE - CANCELLED_BY_BILLING - EXPIRED - DETACH_BILLING - TRIAL_ENDED - Immediate - TRIAL_CONVERTED - PENDING_PAYMENT_EXPIRED - ScheduledCancellation - CustomerArchived - AutoCancellationRule description: Subscription cancel reason nullable: true metadata: type: object additionalProperties: type: string description: Additional metadata for the subscription currentBillingPeriodStart: type: string format: date-time description: Start of the current billing period nullable: true currentBillingPeriodEnd: type: string format: date-time description: End of the current billing period nullable: true pricingType: type: string enum: - FREE - PAID - CUSTOM description: Pricing type paymentCollection: type: string enum: - NOT_REQUIRED - PROCESSING - FAILED - ACTION_REQUIRED description: Payment collection paymentCollectionMethod: type: string enum: - CHARGE - INVOICE - NONE description: The method used to collect payments for a subscription nullable: true billingCycleAnchor: type: string format: date-time description: Billing cycle anchor date nullable: true planId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Plan ID prices: default: [] type: array items: type: object properties: amount: type: number description: The price amount currency: description: The price currency type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf title: Currency featureId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Feature identifier for the price override nullable: true addonId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Addon identifier for the price override nullable: true baseCharge: type: boolean description: Whether this is a base charge override billingCountryCode: type: string maxLength: 255 description: The billing country code of the price blockSize: type: number description: Block size for pricing tiers: type: array items: type: object properties: upTo: type: number description: The up to quantity of the price tier unitPrice: type: object properties: amount: type: number description: The price amount currency: description: ISO 4217 currency code type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf title: Currency required: - amount - currency title: Money description: The unit price of the price tier flatPrice: type: object properties: amount: type: number description: The price amount currency: description: ISO 4217 currency code type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf title: Currency required: - amount - currency title: Money description: The flat fee price of the price tier additionalProperties: false description: Pricing tiers configuration addons: default: [] type: array items: type: object properties: id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Addon ID quantity: type: integer minimum: 0 description: Number of addon instances required: - id - quantity title: SubscriptionAddon description: Addon configuration coupons: default: [] type: array items: type: object properties: id: type: string maxLength: 255 description: Coupon ID name: type: string maxLength: 255 description: Coupon name status: type: string enum: - ACTIVE - EXPIRED - REMOVED description: Coupon status percentOff: type: number description: Percentage discount nullable: true amountsOff: type: array items: type: object properties: amount: type: number description: The price amount currency: description: The price currency type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf title: Currency nullable: true description: Fixed amount discounts by currency required: - id - name - status title: SubscriptionCouponResponse description: Coupon applied to a subscription description: Coupons applied to the subscription futureUpdates: default: [] type: array items: type: object properties: scheduledExecutionTime: type: string format: date-time description: Scheduled execution time subscriptionScheduleType: type: string enum: - DOWNGRADE - PLAN - BILLING_PERIOD - UNIT_AMOUNT - RECURRING_CREDITS - PRICE_OVERRIDE - ADDON - COUPON - MIGRATE_TO_LATEST - ADDITIONAL_META_DATA - BILLING_INFO_METADATA description: Type of scheduled change scheduleStatus: type: string enum: - PENDING_PAYMENT - SCHEDULED - CANCELED - DONE - FAILED description: Status of the scheduled update targetPackage: type: object properties: id: type: string maxLength: 255 description: Target package for the update required: - id nullable: true description: Target package for the update required: - scheduledExecutionTime - subscriptionScheduleType - scheduleStatus title: FutureUpdate description: Scheduled subscription update description: Scheduled future updates for the subscription budget: type: object properties: limit: type: number description: Maximum spending limit hasSoftLimit: type: boolean description: Whether the budget is a soft limit required: - limit - hasSoftLimit additionalProperties: false nullable: true description: Budget configuration minimumSpend: type: object properties: amount: type: number description: The price amount currency: description: The price currency type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf title: Currency description: Minimum spend configuration nullable: true subscriptionEntitlements: default: [] type: array items: type: object properties: type: type: string enum: - FEATURE - CREDIT description: Entitlement type (FEATURE or CREDIT) id: type: string maxLength: 255 description: Feature ID or currency ID required: - type - id title: SubscriptionEntitlementItem description: Subscription entitlement reference description: Entitlements associated with the subscription latestInvoice: type: object properties: billingId: type: string maxLength: 255 description: Invoice billing ID status: type: string enum: - OPEN - CANCELED - PAID description: Invoice status createdAt: type: string format: date-time description: Invoice creation date total: type: number description: Total amount nullable: true amountDue: type: number description: Amount due nullable: true currency: type: string maxLength: 255 description: Invoice currency nullable: true pdfUrl: type: string maxLength: 255 description: Invoice PDF URL nullable: true requiresAction: type: boolean description: Whether payment requires action billingReason: type: string enum: - BILLING_CYCLE - SUBSCRIPTION_CREATION - SUBSCRIPTION_UPDATE - MANUAL - MINIMUM_INVOICE_AMOUNT_EXCEEDED - OTHER nullable: true description: Billing reason required: - billingId - status - createdAt - requiresAction title: LatestInvoice description: Latest invoice for the subscription nullable: true trial: type: object properties: trialEndBehavior: type: string enum: - CONVERT_TO_PAID - CANCEL_SUBSCRIPTION description: Behavior when the trial ends required: - trialEndBehavior title: Trial description: Trial configuration nullable: true required: - id - customerId - billingId - createdAt - startDate - status - pricingType - paymentCollection - planId title: Subscription description: Customer subscription to a plan required: - data title: Response description: Response object BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - DuplicateIntegrationNotAllowed - EntityIsArchivedError - IntegrityViolation - FreePlanCantHaveCompatiblePackageGroupError - SubscriptionMustHaveSinglePlanError - AddonIsCompatibleWithPlan - AddonIsCompatibleWithGroup - DuplicateAddonProvisionedError - ScheduledMigrationAlreadyExistsError - SubscriptionAlreadyOnLatestPlan - EntityIdDifferentFromRefIdError - UnsupportedFeatureType - UnsupportedVendorIdentifier - UnsupportedSubscriptionScheduleType - InvalidEntitlementResetPeriod - IncompatibleSubscriptionAddon - UnPublishedPackage - MeteringNotAvailableForFeatureType - AuthCustomerMismatch - AuthCustomerReadonly - FetchAllCountriesPricesNotAllowed - MemberInvitationError - PlansCircularDependencyError - NoFeatureEntitlementInSubscription - CheckoutIsNotSupported - UnsupportedParameter - PricingModelNotSupportedByBillingIntegration - BillingIntegrationMissing - BillingIntegrationAlreadyExistsError - InvalidMemberDelete - PackageAlreadyPublished - DraftPlanCantBeArchived - DraftAddonCantBeArchived - PlanWithChildCantBeDeleted - PlanCannotBePublishWhenBasePlanIsDraft - PlanCannotBePublishWhenCompatibleAddonIsDraft - PlanIsUsedAsDefaultStartPlan - PlanIsUsedAsDowngradePlan - InvalidAddressError - InvalidQuantity - BillingPeriodMissingError - DowngradeBillingPeriodNotSupportedError - CustomerAlreadyUsesCouponError - CustomerAlreadyHaveCustomerCoupon - SubscriptionAlreadyCanceledOrExpired - TrialMustBeCancelledImmediately - SubscriptionDoesNotHaveBillingPeriod - InvalidCancellationDate - FailedToImportCustomer - FailedToImportSubscriptions - PackagePricingTypeNotSet - InvalidSubscriptionStatus - InvalidArgumentError - EditAllowedOnDraftPackageOnlyError - ResyncAlreadyInProgress - ArchivedCouponCantBeApplied - ImportAlreadyInProgress - AddonHasToHavePriceError - SelectedBillingModelDoesntMatchImportedItemError - CannotArchiveProductError - CannotUnarchiveProductError - CannotDeleteCustomerError - CannotRemovePaymentMethodFromCustomerError - CannotDeleteFeatureError - CannotArchiveFeatureError - InvalidUpdatePriceUnitAmountError - ExperimentAlreadyRunning - ExperimentStatusError - OperationNotAllowedDuringInProgressExperiment - EntitlementsMustBelongToSamePackage - CanNotUpdateEntitlementsFeatureGroup - MeterMustBeAssociatedToMeteredFeature - CannotEditPackageInNonDraftMode - CannotAddOverrideEntitlementToPlan - MissingEntityIdError - NoProductsAvailable - PromotionCodeNotForCustomer - PromotionCodeNotActive - PromotionCodeMaxRedemptionsReached - PromotionCodeMinimumAmountNotReached - PromotionCodeCustomerNotFirstPurchase - AddonWithDraftCannotBeDeletedError - CannotReportUsageForEntitlementWithMeterError - RecalculateEntitlementsError - ImportSubscriptionsBulkError - InvalidMetadataError - CannotUpsertToPackageThatHasDraft - IntegrationValidationError - AwsMarketplaceIntegrationValidationError - AwsMarketplaceIntegrationError - DataExportIntegrationError - HubspotIntegrationError - DuplicateProductValidationError - AmountTooLarge - CustomerHasNoEmailAddress - MergeEnvironmentValidationError - EntitlementLimitExceededError - EntitlementUsageOutOfRangeError - UsageMeasurementDiffOutOfRangeError - AddonQuantityExceedsLimitError - AddonDependencyMissingError - PackageGroupMinItemsError - CannotUpdateUnitTransformationError - SingleSubscriptionCantBeAutoCancellationTargetError - MultiSubscriptionCantBeAutoCancellationSourceError - ChangingPayingCustomerIsNotSupportedError - RequiredSsoAuthenticationError - InvalidDoggoSignatureError - InvalidReceivedSignatureError - CannotDeleteDefaultIntegration - CannotChangeBillingIntegration - FailedToResolveBillingIntegration - WorkflowTriggerNotFound - DeprecatedEstimateSubscriptionError - FeatureConfigurationExceededLimitError - FeatureNotBelongToFeatureGroupError - FeatureGroupMissingFeaturesError - VersionExceedsMaxValueError - CannotUpdateExpireAtForExpiredCreditGrantError - ExpireAtMustBeLaterThanEffectiveAtError - OfferAlreadyExists - DraftAlreadyExists - CreditGrantAlreadyVoided - CreditGrantCannotBeVoided - InvalidTaxId - ObjectAlreadyBeingUsedByAnotherRequestError - TooManySubscriptionsPerCustomer - TooManyCustomCurrencies - StripeError - SchedulingAtEndOfBillingPeriod - ApiKeyExpired - ApiKeyHasExpiry nullable: true required: - message - code UnauthenticatedErrorResponseDto: type: object properties: message: type: string code: type: string enum: - Unauthenticated nullable: true required: - message - code ForbiddenErrorResponseDto: type: object properties: message: type: string code: type: string enum: - IdentityForbidden - AccessDeniedError - NoFeatureEntitlementError - GovernanceNotEnabled nullable: true required: - message - code NotFoundErrorResponseDto: type: object properties: message: type: string code: type: string enum: - CustomerNotFound - CustomCurrencyNotFound - CreditGrantNotFound - MemberNotFound - PackageGroupNotFound - AddonNotFound - AddonsNotFound - EnvironmentMissing - IntegrationNotFound - VendorIsNotSupported - CouponNotFound - FutureUpdateNotFound - CustomerNoBillingId - SubscriptionNoBillingId - StripeCustomerIsDeleted - InitStripePaymentMethodError - PreparePaymentMethodFormError - AccountNotFoundError - ExperimentNotFoundError - NoDraftOfferFound - PromotionCodeNotFound - FailedToCreateCheckoutSessionError - PaymentMethodNotFoundError - ProductNotFoundError - ProductNotPublishedError - MissingBillingInvoiceError - BillingInvoiceStatusError - FeatureGroupNotFoundError - CannotArchiveFeatureGroupError - OfferNotFound - CustomerResourceNotFound - FeatureNotFound - PriceNotFound - NoActiveSubscriptionForCustomer - PlanNotFound - PromotionalEntitlementNotFoundError - SubscriptionNotFound - ApiKeyNotFound nullable: true required: - message - code TooManyRequestsErrorResponseDto: type: object properties: message: type: string code: type: string enum: - RateLimitExceeded nullable: true required: - message - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: Server API Key ````