Skip to navigation
API ReferencePlans and billingSubscriptions

Update a subscription

Changes the seat quantity of a plan with per_seat: true, or the metadata. A new quantity applies to the recurring fee and included credits from the next period. Seats added mid-period are not charged until then. To move to a different plan, use change_plan.

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.
quantityintegerOptional>=1

Seats, on a plan with per_seat: true. Takes effect for the recurring fee at the next period.

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 updated 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
429
Too Many Requests Error
500
Internal Server Error