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

A reference-by-id price diff applied to the prices of the plan's current version. Every id references an existing price created via POST /prices; inline price definitions are not accepted. An empty body copies the current prices into the new version unchanged. A version must carry at least one price, so a diff that would leave none is rejected.

addPrices
string[]

Prices to add to the version. Each must not already be on the plan's current version.

Unique identifier for a price

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

Prices to remove. Each must be on the plan's current version.

Unique identifier for a price

Pattern: ^price_[a-zA-Z0-9]+$
replacePrices
object[]

Prices to swap in place, preserving the slot's lineage so the price keeps its identity where the plan is configured for stable price ids. replacesPriceId must be on the plan's current version; withPriceId is the new price.

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 for draft review.

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:
draft,
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. Optimistic-concurrency token: read this value and echo it back as an If-Match header on a draft-price-mutation request to reject the write (412) if the draft changed since this read.

prices
object[]
required

The price slots that make up this version.

publishedAt
string<date-time>

When this version was published. Absent for draft versions.

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]+$