Update Subscription Version

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

string

required

The unique identifier of the subscription

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
}

object

Details about individual prices to include in this subscription version

Show Prices Object Properties

array

Array of existing price IDs to include in this subscription version

array

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

string

required

The unique identifier of the product for this price

string

required

The pricing model type (e.g., “unit”, “tiered”, “volume”)

string

required

The amount charged per unit for this price. This is a simplified parameter - see pricing models reference for complete configuration options

array

Array of price bundles to include in this subscription version

Show PriceBundle Properties

string

required

Name of the price bundle

string

required

Description of the price bundle

string

required

Unique identifier of the bundle

array

Array of existing price IDs to include in this bundle

array

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

string

required

The unique identifier of the product for this price

string

required

The pricing model type (e.g., “unit”, “tiered”, “volume”)

string

required

The amount charged per unit for this price. This is a simplified parameter - see pricing models reference for complete configuration options

string

Optional description of what is changing in this version

datetime

Optional start date for when this version should become active

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"
}

string

Unique identifier for the subscription version

datetime

When the subscription version was created in ISO 8601 format

uuid

The organization ID that owns this subscription version

string

The quote ID associated with this subscription version

string

Optional description of what changed in this version

datetime

Optional start date for this subscription version in ISO 8601 format

datetime

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

array

Groups of prices included in this subscription version

Show Price Group

string

The name of the price group

string

A description of what this price group represents

string

The bundle ID this price group is associated with

array

Array of price IDs included in this price group

string

Current status of the subscription version. Possible values: draft or published

⌘I

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

API Reference

Billing Events & Usage Metering

Bundles

Credit Grants

Credit Notes

Customers

Invoices

Plans

Products

Refunds

Subscriptions

Subscription Versions

Wallets

Update Subscription Version

Path Parameters

Request

Response

​Path Parameters

​Request

​Response

Path Parameters

Request

Response