Creates a new version of an existing subscription. This is used when you need to change a subscription (upgrade, downgrade, add features, etc.).
Path Parameters The unique identifier of the subscription to create a new version for
Request { "prices" : { "existingPriceIds" : [ "price_0000000000000001" ], "newPrices" : [ { "productId" : "prod_0000000000000001" , "type" : "unit" , "unitAmount" : "59.99" } ] }, "priceBundles" : [ { "name" : "Core Features" , "description" : "Essential platform capabilities" , "bundleId" : "bun_0000000000000001" , "existingPriceIds" : [ "price_0000000000000002" ], "newPrices" : [ { "productId" : "prod_0000000000000002" , "type" : "unit" , "unitAmount" : "29.99" } ] } ], "changeDescription" : "Added new features to enterprise plan" , "startDate" : "2024-02-01T00:00:00Z" , "isMidCycle" : false } Details about individual prices to include in this subscription version Show Prices Object Properties
Array of existing price IDs to include in this subscription version
Array of new prices to create and include in this subscription version.
See the Pricing Models API
Reference for
detailed information on all supported pricing models and their parameters. Show Basic NewPrice Properties
The unique identifier of the product for this price
The pricing model type (e.g., “unit”, “tiered”, “volume”)
The amount charged per unit for this price. This is a simplified
parameter - see pricing models reference for complete configuration
options
Array of price bundles to include in this subscription version Show PriceBundle Properties
Description of the price bundle
Unique identifier of the bundle
Array of existing price IDs to include in this bundle
Array of new prices to create and include in this bundle. See the Pricing
Models API Reference
for detailed information on all supported pricing models and their
parameters. Show Basic NewPrice Properties
The unique identifier of the product for this price
The pricing model type (e.g., “unit”, “tiered”, “volume”)
The amount charged per unit for this price. This is a simplified
parameter - see pricing models reference for complete configuration
options
Optional description of what is changing in this version
Optional start date for when this version should become active
Whether this version change is happening mid-billing cycle
Response { "id" : "subver_0000000000000001" , "createdAt" : "2024-01-01T12:00:00Z" , "organizationId" : "00000000-0000-0000-0000-000000000001" , "quoteId" : "quo_0000000000000001" , "changeDescription" : "Added new features to enterprise plan" , "startDate" : "2024-02-01T00:00:00Z" , "endDate" : "2024-12-31T23:59:59Z" , "priceGroups" : [ { "name" : "Core Features" , "description" : "Essential platform capabilities" , "bundleId" : "bun_0000000000000001" , "priceIds" : [ "pri_0000000000000001" , "pri_0000000000000002" , "pri_0000000000000003" ] }, { "name" : "Add-ons" , "description" : "Optional additional features" , "bundleId" : "bun_0000000000000002" , "priceIds" : [ "pri_0000000000000004" , "pri_0000000000000005" ] } ], "status" : "published" } Unique identifier for the subscription version
When the subscription version was created in ISO 8601 format
The organization ID that owns this subscription version
The quote ID associated with this subscription version
Optional description of what changed in this version
Optional start date for this subscription version in ISO 8601 format
End date determined by us for this subscription version in ISO 8601 format. If
empty, the subscription version is open-ended
Groups of prices included in this subscription version The name of the price group
A description of what this price group represents
The bundle ID this price group is associated with
Array of price IDs included in this price group
Current status of the subscription version. Possible values: draft or
published
