Create Subscription Version

POST

subscriptions

{id}

versions

{
  "prices": {
    "existingPriceIds": ["price_0000000000000001"],
    "newPrices": [
      {
        "productId": "prod_0000000000000001",
        "type": "unit",
        "feeType": "metered",
        "billingDirection": "arrears",
        "billingInterval": "monthly",
        "unitPricingModel": {
          "pricePerUnit": "59.99"
        }
      }
    ]
  },
  "priceBundles": [
    {
      "name": "Core Features",
      "description": "Essential platform capabilities",
      "bundleId": "bun_0000000000000001",
      "existingPriceIds": ["price_0000000000000002"],
      "newPrices": [
        {
          "productId": "prod_0000000000000002",
          "type": "unit",
          "feeType": "metered",
          "billingDirection": "arrears",
          "billingInterval": "monthly",
          "unitPricingModel": {
            "pricePerUnit": "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": "published"
}

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

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",
        "feeType": "metered",
        "billingDirection": "arrears",
        "billingInterval": "monthly",
        "unitPricingModel": {
          "pricePerUnit": "59.99"
        }
      }
    ]
  },
  "priceBundles": [
    {
      "name": "Core Features",
      "description": "Essential platform capabilities",
      "bundleId": "bun_0000000000000001",
      "existingPriceIds": ["price_0000000000000002"],
      "newPrices": [
        {
          "productId": "prod_0000000000000002",
          "type": "unit",
          "feeType": "metered",
          "billingDirection": "arrears",
          "billingInterval": "monthly",
          "unitPricingModel": {
            "pricePerUnit": "29.99"
          }
        }
      ]
    }
  ],
  "changeDescription": "Added new features to 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. Each price must include the pricing model object matching the type field (e.g., unitPricingModel for type unit). See the Pricing Models API Reference for all supported models and their parameters.

Show Common NewPrice Properties

string

required

The unique identifier of the product for this price

string

required

The pricing model type: unit, fixed, tiered, graduated_tiered, prepaid_tiered, prepaid_fixed_tiered, tiered_percentage, graduated_percentage, volume_percentage

string

Fee classification: fixed or metered. Defaults to the product’s fee type if omitted.

string

When the charge is collected: advance (start of period) or arrears (end of period). Defaults to the product’s payment terms if omitted.

string

required

Billing interval: monthly, quarterly, or yearly

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. Each price must include the pricing model object matching the type field (e.g., unitPricingModel for type unit). See the Pricing Models API Reference for all supported models and their parameters.

Show Common NewPrice Properties

string

required

The unique identifier of the product for this price

string

required

The pricing model type: unit, fixed, tiered, graduated_tiered, prepaid_tiered, prepaid_fixed_tiered, tiered_percentage, graduated_percentage, volume_percentage

string

Fee classification: fixed or metered. Defaults to the product’s fee type if omitted.

string

When the charge is collected: advance (start of period) or arrears (end of period). Defaults to the product’s payment terms if omitted.

string

required

Billing interval: monthly, quarterly, or yearly

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",
        "feeType": "metered",
        "billingDirection": "arrears",
        "billingInterval": "monthly",
        "unitPricingModel": {
          "pricePerUnit": "59.99"
        }
      }
    ]
  },
  "priceBundles": [
    {
      "name": "Core Features",
      "description": "Essential platform capabilities",
      "bundleId": "bun_0000000000000001",
      "existingPriceIds": ["price_0000000000000002"],
      "newPrices": [
        {
          "productId": "prod_0000000000000002",
          "type": "unit",
          "feeType": "metered",
          "billingDirection": "arrears",
          "billingInterval": "monthly",
          "unitPricingModel": {
            "pricePerUnit": "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": "published"
}

API Reference

Billing Events & Usage Metering

Bundles

Credit Grants

Credit Notes

Customers

Invoices

Plans

Products

Refunds

Subscriptions

Subscription Versions

Wallets

Create Subscription Version

Path Parameters

Request

Response

​Path Parameters

​Request

​Response

Path Parameters

Request

Response