Skip to navigation
API ReferencePlans and billingSubscriptions

Cancel a subscription

Cancels at the end of the current period by default. With immediately: true, it ends now: a postpaid subscription gets a final invoice for what has accrued, and unused prepaid credits stay on the balance until they expire. Pending outcome charges still settle on their own clocks.

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.

Path parameters

subscription_idstringRequired

The subscription ID (sub_...).

Request

This endpoint expects an object.
immediatelybooleanOptionalDefaults to false
End now. Otherwise the subscription ends at the end of the current period.

Response

The canceled or canceling 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
429
Too Many Requests Error
500
Internal Server Error