Skip to main content
POST
Create plan experiment version
This reference describes API version 2026-07-24. Send Commet-Version: 2026-07-24 with your request.

Authorizations

x-api-key
string
header
required

Headers

Idempotency-Key
string

Unique key used to safely retry this write for 24 hours without applying it twice.

Required string length: 1 - 200
Commet-Version
string
default:2026-07-24

API version used by this reference. Send this header to select this contract explicitly.

Path Parameters

id
string
required
code
string
required

The experiment's own code, without the plan code: price-test.

Body

application/json
prices
object[]
currencies
object[]

Currencies the current version does not sell, with the exchange rate (local units per USD) used for the amounts not listed, credit purchases, add-ons and overage.

maxPlanCredits
integer | null

Credits plans that roll over unused credits: the most plan credits a subscription can hold. Null removes the cap.

Required range: 1 <= x <= 2147483647
maxPlanBalance
integer | null

Balance plans that roll over unused balance: the most plan balance a subscription can hold, in USD cents. Other currencies convert it with the plan's exchange rate unless the dashboard sets a custom amount for that currency. Null removes the cap.

Required range: 1 <= x <= 2147483647

Response

Success

id
string
required

Public plan version ID.

label
string
required

The plan's versions are numbered 1, 2, 3; an experiment's own versions read with its code, such as price-test 2.

number
integer | null
required

The plan's version number. Null for a version that only belongs to an experiment; an experiment version made current takes the next number.

Required range: -9007199254740991 <= x <= 9007199254740991
experiment
object | null
required

The experiment this version belongs to, if any.

isCurrent
boolean
required

Whether new buyers get this version.

parentVersionId
string | null
required

The version this one was created from.

subscriptionCount
integer
required

Active, trialing, past due and paused subscriptions on it.

Required range: -9007199254740991 <= x <= 9007199254740991
maxPlanCredits
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
maxPlanBalance
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
prices
object[]
required
createdAt
string<date-time>
required
object
string
required
Allowed value: "plan_version"
livemode
boolean
required