Skip to main content
PATCH
Replace a price on a draft

Authorizations

Authorization
string
header
required

API key authentication

Headers

If-Match
string

Optional optimistic-concurrency precondition — the draft version's updatedAt timestamp as read from a prior GET. If present and it no longer matches the version's current updatedAt, the request is rejected with 412 (draft_modified). Omit to skip the check.

Path Parameters

id
string
required

Unique identifier for a plan

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

The version number within the plan (1-based).

Required range: x >= 1
priceId
string
required

Unique identifier for a price

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

Body

application/json

Swaps the price at the path's priceId slot for withPriceId on a draft version, preserving the slot's lineage. withPriceId must differ from the path priceId.

withPriceId
string
required

Unique identifier for a price

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

Response

The updated draft version

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 was cloned from at mint time. Absent for versions minted before this field existed or through the legacy fused write path. Used to detect a superseded base when moving the default.

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