Skip to main content
POST
Create subscription
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.

Body

application/json
customerId
string
required
Required string length: 1 - 200
planId
string
required
Minimum string length: 1
billingInterval
enum<string> | null
Available options:
weekly,
monthly,
quarterly,
semiannual,
yearly,
one_time
priceId
string

Public price ID. When omitted, Commet selects the default price for the billing interval and still applies its market pricing.

Minimum string length: 1
initialSeats
object
provider

Payment provider name or exact public payment connection ID for the initial checkout. Overrides country routing when present.

Available options:
stripe,
commet,
dlocal
paymentMethodTypes
enum<string>[]

Payment methods the initial checkout may offer. Restricts what the checkout already offers for the buyer's country, currency and payment connection; it never enables a method the connection does not have and never changes routing. When none of them is available to the buyer, the checkout shows that it cannot accept payments.

Minimum array length: 1
Available options:
card,
oxxo,
mercado_pago,
google_pay,
smartpix
name
string
startDate
string<date-time>
successUrl
string<uri>
prepaidPeriods
integer

Billing periods of the subscription's interval paid with the first payment, including the current one. Defaults to 1. The interval does not change: each paid period renews at zero and the subscription renews normally after the last one unless cancelAtPeriodEnd is true.

Required range: 1 <= x <= 60
cancelAtPeriodEnd
boolean

Schedules the cancellation from creation so the subscription ends after its last paid period and never renews with any payment method.

planVersionId
string

Public ID of a published version of the plan, current or not, including an experiment's versions. The subscription is created on that version and stays on it: checkout charges its price and activation grants its credits, add-ons and credit packs. When omitted, the subscription gets the current version, or the version an experiment code (planCode <plan code>:<experiment code>) sells.

Minimum string length: 1
offerId
any
promoCode
string
Minimum string length: 1
customTrialDays
integer

Trial length in days, replacing the price's trial. A customer who already had this plan, in a trial or paying, gets no trial and goes through the regular checkout.

Required range: 0 <= x <= 9007199254740991
skipTrial
boolean
default:false

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
checkoutProvider
enum<string> | null
required

Payment provider resolved for this checkout when the subscription response was created. This is an informational snapshot and may differ when the checkout is loaded if its country or the organization's routing changes.

Available options:
stripe,
commet,
dlocal
priceId
string | null
required
object
string
required
Allowed value: "subscription"
livemode
boolean
required