Skip to navigation
API ReferencePlans and billingSubscriptions

Retrieve a 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.

Path parameters

subscription_idstringRequired

The subscription ID (sub_...).

Response

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