Skip to navigation
API ReferencePlans and billingSubscriptions

Create a subscription

Puts a customer on a plan, for sales-led contracts. Self-serve purchases go through checkout(), which creates the subscription after payment. A plan with a recurring fee needs a saved payment method when collection_method is charge_automatically, or the subscription starts incomplete. A customer has at most one active subscription.

Authentication

AuthorizationBearer

A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.

Request

This endpoint expects an object.
planstringRequired

The plan (ID or key).

customer_idstringOptional
external_customer_idstringOptional
collection_methodenumOptional

charge_automatically charges the saved payment method. send_invoice emails a payment link from the provider.

Allowed values:
start_atdatetimeOptional
When the first period starts. Defaults to now.
overdraft_limitstringOptional
Overrides the plan's overdraft allowance for this customer.
credit_limitobjectOptional
An amount of money in the currency's minor unit.
quantityintegerOptional>=1Defaults to 1

Seats, on a plan with per_seat: true.

metadatamap from strings to stringsOptional
Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

Response

The new subscription.
idstring
object"subscription"
customerstring
planstring
statusenum

incomplete is waiting for a first payment or a payment method. past_due has an unpaid invoice; checks are denied until it’s paid.

Allowed values:
collection_methodenum

charge_automatically charges the saved payment method. send_invoice emails a payment link from the provider.

Allowed values:
current_period_startdatetime
current_period_enddatetime
cancel_at_period_endboolean
metadatamap from strings to strings
Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.
livemodeboolean
created_atdatetime
canceled_atdatetimeOptional
scheduled_planstringOptional

The plan taking over at current_period_end, if a change is scheduled.

overdraft_limitstringOptional
credit_limitobjectOptional
An amount of money in the currency's minor unit.
quantityintegerOptional

Seats. 1 unless the plan has per_seat: true.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
424
Failed Dependency Error
429
Too Many Requests Error
500
Internal Server Error