Skip to main content
POST
Create a new version

Authorizations

Authorization
string
header
required

Your account's secret key: Authorization: Bearer sk_test_… or sk_live_…. Server-side only.

Headers

Idempotency-Key
string

A unique key per operation (a UUID works). Retrying with the same key returns the original response.

Path Parameters

productID
string<uuid>
required

Product ID.

Body

application/json
billingCycle
enum<string> | null

Billing cycle: weekly, monthly or annual. Required for subscription and prepaid.

Available options:
weekly,
monthly,
annual,
null
basePrice
string | null

Base price as a decimal string ("49.90"): the fixed amount of the purchase or of each cycle.

grants
object[]

Usage credits the version grants, one entry per meter. on: cycle credits at each new subscription period; on: payment credits when the payment is confirmed.

Response

Version created in draft.

A product version: a snapshot of its pricing. A published version never changes; to change the price, create another.

id
string<uuid>
productId
string<uuid>
version
integer

Sequential version number (1, 2, 3…).

billingCycle
enum<string> | null

weekly, monthly or annual; null for non-recurring products.

Available options:
weekly,
monthly,
annual,
null
basePrice
string | null

Base price as a decimal string; null for a usage-only product.

status
enum<string>

draft (editable), published (sellable, fixed pricing) or archived.

Available options:
draft,
published,
archived
isDefault
boolean

Whether this is the version a buyer gets when nothing names another. A published version with isDefault: false is an offer: it is only sold through a payment link created with productVersionId.

publishedAt
string<date-time> | null
commitmentAmount
string | null

Minimum charged per cycle, as a decimal string; null when there is none.

commitmentResets
boolean

true: the unused minimum is lost at cycle close. false: it rolls over.

consumptionFloor
string | null

Balance below which usage recording is refused. See VersionConsumption.floor.

grants
object[]

Usage credits the version grants.