Skip to main content
POST
Change subscription version
This reference describes API version 2026-07-31. Send Commet-Version: 2026-07-31 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-31

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

Path Parameters

id
string
required

Body

application/json
planVersionId
string
required

A published version of the subscription's plan.

effective
enum<string>
required

now changes features, limits and the included credits or balance at once (the included difference is added to or subtracted from the plan credits or plan balance: an increase first pays any plan-part debt, a decrease never creates new debt, and purchased credits and purchased balance are untouched) and charges the new price from the next renewal. period_end changes everything at the next renewal. There is never a proration charge or refund.

Available options:
now,
period_end

Response

Success

id
string
required
customerId
string
required
plan
object
required
name
string
required
description
string | null
required
status
enum<string>
required
Available options:
draft,
pending_payment,
trialing,
active,
past_due,
paused,
canceled
billingInterval
enum<string> | null
required
Available options:
weekly,
monthly,
quarterly,
semiannual,
yearly,
one_time
trialEndsAt
string<date-time> | null
required
currentPeriod
object | null
required
cancellation
object | null
required
cancelAtPeriodEnd
boolean
required
scheduledPlanChange
object | null
required
startDate
string<date-time>
required
endDate
string<date-time> | null
required
billingDayOfMonth
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
nextBillingDate
string<date-time> | null
required
checkoutUrl
string | null
required
hasPaymentMethod
boolean
required

Whether Commet can charge this subscription on its own at its next charge (the trial end or the renewal). A trial that started without a payment method reports false until the customer adds one for this subscription; a payment method saved for another subscription does not count. A subscription on a free plan reports false.

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
planVersion
object | null
required

The plan version whose terms the subscription has now. It keeps paying and receiving everything from this version until it is moved.

offerApplications
object[]
required
scheduledVersionChange
object | null
required

A move to another version of the plan pending for the next renewal.

consumptionModel
enum<string> | null
required
Available options:
metered,
credits,
balance
features
object[]
required
credits
object | null
required
balance
object | null
required
priceId
string | null
required
object
string
required
Allowed value: "subscription"
livemode
boolean
required
planGrant
object