Skip to navigation
API ReferencePlans and billingSubscriptions

Change plan

Schedules a move to another plan at the start of the next period. The plan must have the same billing mode and currency. Mid-period changes with proration aren’t supported.

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.
planstringRequired

The plan (ID or key) to move to at the next period.

Response

The subscription, with the change scheduled.
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