Skip to navigation
API ReferencePlans and billingPlans

Create a plan

A plan sets the billing mode, the rates for usage events and outcomes, and the limits. Prepaid plans keep a balance in one credit type and price in credits (credits_per_unit). Postpaid plans accrue charges in the plan currency (unit_amount_decimal) and invoice them at the end of each period. Rates can change until the first subscription starts; after that, create a new 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.

Request

This endpoint expects an object.
keystringRequiredformat: "^[a-z][a-z0-9_]{1,63}$"
namestringRequired
billing_modeenumRequired

prepaid: a credit balance that must cover charges, topped up or granted in advance. postpaid: charges accrue in money and are invoiced at period end.

Allowed values:
currencystringRequired
intervalenumRequired
Allowed values:
rateslist of objectsRequired
descriptionstringOptional
credit_typestringOptional

Prepaid. The credit type (ID or key) the balance is kept in.

recurring_feeobjectOptional
An amount of money in the currency's minor unit.
included_creditsobjectOptional
Prepaid. Credits granted at the start of each period.
top_upobjectOptional
Prepaid. Lets customers buy more credits through checkout.
allowanceslist of objectsOptional

Refills and caps on the plan’s balance. See Usage windows.

poolslist of objectsOptional

Named balance pools, in drawdown order. See Pools.

per_seatbooleanOptional

recurring_fee and included_credits are per seat, multiplied by the subscription’s quantity. Default false.

default_spend_limitobjectOptional

The spend limit each new subscription on the plan starts with. A customer-set limit may replace it, up to ceiling.

overdraft_limitstringOptional
Prepaid. How far below zero the balance may go, in credits. Default "0".
credit_limitobjectOptional
An amount of money in the currency's minor unit.
minimum_commitmentobjectOptional
An amount of money in the currency's minor unit.
invoice_grace_periodstringOptional
Postpaid. How long after period end the invoice finalizes, so late events land. Default PT1H, maximum P3D.
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 plan.
idstring
object"plan"
keystring
namestring
statusenum
Allowed values:
billing_modeenum

prepaid: a credit balance that must cover charges, topped up or granted in advance. postpaid: charges accrue in money and are invoiced at period end.

Allowed values:
currencystring
intervalenum
Allowed values:
rateslist of objects
has_subscriptionsboolean
Once true, pricing can't change.
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
descriptionstringOptional
credit_typestringOptional
recurring_feeobjectOptional
An amount of money in the currency's minor unit.
included_creditsobjectOptional
Prepaid. Credits granted at the start of each period.
top_upobjectOptional
Prepaid. Lets customers buy more credits through checkout.
allowanceslist of objectsOptional

Refills and caps on the plan’s balance. See Usage windows.

poolslist of objectsOptional

Named balance pools, in drawdown order. See Pools.

per_seatbooleanOptional

recurring_fee and included_credits are per seat, multiplied by the subscription’s quantity. Default false.

default_spend_limitobjectOptional

The spend limit each new subscription on the plan starts with. A customer-set limit may replace it, up to ceiling.

overdraft_limitstringOptional
credit_limitobjectOptional
An amount of money in the currency's minor unit.
minimum_commitmentobjectOptional
An amount of money in the currency's minor unit.
invoice_grace_periodstringOptional
actorobjectOptional
Who last changed the plan.

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