POST
/
subscriptions
/
{id}
/
versions
{
  "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
}

{
  "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": "active"
}

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

​
id
string
required

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
}
​
prices
object

Details about individual prices to include in this subscription version

​
priceBundles
array

Array of price bundles to include in this subscription version

​
changeDescription
string

Optional description of what is changing in this version

​
startDate
datetime

Optional start date for when this version should become active

​
isMidCycle
boolean

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": "active"
}
​
id
string

Unique identifier for the subscription version

​
createdAt
datetime

When the subscription version was created in ISO 8601 format

​
organizationId
uuid

The organization ID that owns this subscription version

​
quoteId
string

The quote ID associated with this subscription version

​
changeDescription
string

Optional description of what changed in this version

​
startDate
datetime

Optional start date for this subscription version in ISO 8601 format

​
endDate
datetime

End date determined by us for this subscription version in ISO 8601 format. If empty, the subscription version is open-ended

​
priceGroups
array

Groups of prices included in this subscription version

​
status
string

Current status of the subscription version. Possible values: draft, active, superseded, canceled