PATCH
/
subscriptions
/
{id}
/
versions
/
{versionId}
{
  "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": "Updated pricing for 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": "published"
}
Updates an existing subscription version that is in the draft state. Use this endpoint to modify a version before it is published.

Path Parameters

id
string
required
The unique identifier of the subscription
versionId
string
required
The unique identifier of the subscription version to update

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": "Updated pricing for 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": "published"
}
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 or published