POST
/
subscriptions
/
{id}
/
versions
{
  "effectiveDate": "2024-05-01T00:00:00Z",
  "changes": {
    "add": [
      {
        "price": {
          "productId": "prod_0000000000000000000000",
          "type": "unit",
          "unitAmount": "59.99"
        }
      }
    ],
    "replace": [
      {
        "priceId": "price_0000000000000000000000",
        "type": "unit",
        "unitAmount": "299.99"
      }
    ],
    "remove": [
      "price_0000000000000002222222"
    ]
  }
}


{
  "id": "<string>",
  "effectiveStartDate": {},
  "effectiveEndDate": {},
  "status": "<string>",
  "items": {
    "priceId": "<string>",
    "type": "<string>",
    "unitAmount": "<string>",
    "quantity": "<string>",
    "bundleId": "<string>",
    "prices": {
      "priceId": "<string>",
      "type": "<string>",
      "unitAmount": "<string>"
    }
  },
  "thresholds": {
    "type": "<string>",
    "value": "<string>",
    "interval": "<string>",
    "scope": {
      "type": "<string>",
      "ids": {}
    }
  },
  "discounts": {}
}

When you need to change a subscription (upgrade, downgrade, add features, etc.), you create a new version. When creating a new version, we use a differential approach. Here you specify the effective date of the version, and any additions, replacements, or removals of prices you want to make.

Each version is associated with 1-many prices, such that the hierarchy is, for example:

  • Subscription
    • Version 1
      • Price A
      • Price B
    • Version 2
      • Price B (continuation)
      • Price C (replaces Price A)

​
Version Lifecycle

Each subscription version goes through a clear lifecycle:

  • Draft: Initial state after creation, before activation
  • Pending: Scheduled for future activation (for changes with future effective dates)
  • Active: Currently effective version
  • Inactive: Previously active version that has been superseded
  • Cancelled: A version that was created but never activated

A subscription maintains a timeline of these versions, ensuring a complete audit trail of subscription changes over time.

​
Request

{
  "effectiveDate": "2024-05-01T00:00:00Z",
  "changes": {
    "add": [
      {
        "price": {
          "productId": "prod_0000000000000000000000",
          "type": "unit",
          "unitAmount": "59.99"
        }
      }
    ],
    "replace": [
      {
        "priceId": "price_0000000000000000000000",
        "type": "unit",
        "unitAmount": "299.99"
      }
    ],
    "remove": [
      "price_0000000000000002222222"
    ]
  }
}
​
effectiveDate
datetime
required

The effective date for the new subscription version. This is when the specified changes will take effect.

​
changes
object
required

Contains the differential changes for the new subscription version, including additions, replacements, and removals of prices.

​
Response

​
id
string

The unique identifier for the subscription version.

​
effectiveStartDate
datetime

The date and time when this subscription version becomes effective.

​
effectiveEndDate
datetime

The date and time when this subscription version ends, if applicable. This field is null if no end date is set.

​
status
string

The current status of the subscription version. For example, pending indicates that the version is awaiting activation.

​
items
[]Item

An array of pricing items included in this subscription version. Each item represents either a single price modification or a bundled set of prices.

​
thresholds
[]Threshold

An array of thresholds applied to this subscription version. Thresholds define spending or usage limits over a specified interval.

​
discounts
[]Discount

An array of discounts applied to this subscription version. If no discounts are applied, this array will be empty.