Skip to main content
PATCH
cURL
Update a base price or market price variant. Removing a base market override is rejected while a variant depends on it. Offer terms are managed through Offers. Publishes a new current version of the plan. New buyers get it; existing subscribers stay on their version until you move them with Change subscription version or Move subscribers to a plan version.

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-08-27

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

Path Parameters

id
string
required
priceId
string
required

Body

application/json
price
integer
Required range: 0 <= x <= 9007199254740991
isDefault
boolean
trialDays
integer
Required range: 0 <= x <= 730
trialRequiresPaymentMethod
boolean

Set to false so the price's free trial starts without a payment method. Requires trialDays on the price.

includedBalance
integer | null
Required range: -9007199254740991 <= x <= 9007199254740991
includedCredits
integer | null
Required range: -9007199254740991 <= x <= 9007199254740991
metadata
object

Metadata keys to merge into the existing price metadata.

marketPrices
object[]

Response

Success

id
string
required

Public plan price ID.

planId
string
required
billingInterval
enum<string>
required
Available options:
weekly,
monthly,
quarterly,
semiannual,
yearly,
one_time
price
integer
required

Price in the currency's minor unit (for example, cents for USD).

Required range: -9007199254740991 <= x <= 9007199254740991
isDefault
boolean
required
trialDays
integer
required
Required range: -9007199254740991 <= x <= 9007199254740991
trialRequiresPaymentMethod
boolean | null
required

Whether the price's free trial needs a payment method to start. When false, a new subscription starts trialing right away without checkout; without a payment method added by the trial end, the customer moves to the plan group's default plan, or the subscription is canceled when there is none. Null when the price has no trial.

includedBalance
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
includedCredits
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
offerId
string | null
required

Automatic introductory offer for this price.

inheritsFromPriceId
string | null
required

Public base price ID for a market price variant, or null for a base price.

metadata
object
required

Application metadata. Variant display names may use metadata.name.

marketPrices
object[]
required

Country-market overrides. Variants inherit their base price for every market not listed.

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
object
string
required
Allowed value: "plan_price"
livemode
boolean
required