Skip to main content
POST
Mint a plan version

Authorizations

Authorization
string
header
required

API key authentication

Path Parameters

id
string
required

Unique identifier for a plan

Pattern: ^plan_[a-zA-Z0-9]+$

Body

application/json

The price set the new version is to hold. Every price ID references an existing price created via POST /prices; inline price definitions are not accepted. The change against the plan's current version follows from the keys: a key on both sides with a different price ID replaces that line and keeps its identity, a key only in this request adds a line, and a key the current version holds and this request omits removes that line. An entry with no key adds a line under a generated key; it is never matched to an existing line by price ID. A version must carry at least one price, so an empty set is rejected.

prices
(string | object)[]
required

The full price set the new version holds. To move off the previous addPrices, removePrices and replacePrices fields: a replacePrices entry becomes the same key with the new price ID, a removePrices entry becomes an omitted key, and an addPrices entry becomes a new entry.

Minimum array length: 1

Either a price ID on its own, or a price ID with the key that names its line.

Pattern: ^price_[a-zA-Z0-9]+$
basedOnVersionId
string

The ID of the plan version you read the current price set from. Supply it to be told when the plan has moved on: the request is rejected with 409 if the plan's current version is no longer this one, so a set built from a stale read cannot drop a line another caller has just added. Omit it to write the set unconditionally.

Pattern: ^pver_[a-zA-Z0-9]+$

Response

The newly minted version, published and now the plan's default

A single plan version, including its price slots. Extends the list summary with the version's prices.

id
string
required

Unique identifier for a plan version

Pattern: ^pver_[a-zA-Z0-9]+$
object
enum<string>
required
Available options:
plan_version
versionNumber
integer
required

Monotonic version number within the plan, starting at 1.

Required range: x >= 1
status
enum<string>
required

Lifecycle status of the version.

Available options:
published,
archived
isDefault
boolean
required

Whether this version is the plan's current default (live) version.

subscriptionCount
integer
required

Number of committed-status subscriptions pinned to this version at creation time. Not a live-billing cohort.

Required range: x >= 0
updatedAt
string<date-time>
required

When this version was last modified.

prices
object[]
required

The price slots that make up this version.

publishedAt
string<date-time>

When this version was published.

basedOnVersionId
string

The version this one follows on from — the version that was live when this one was created, and whose prices it was built from. Absent for versions created before this field existed.

Pattern: ^pver_[a-zA-Z0-9]+$