Skip to navigation
API ReferenceCredits and holdsCredit grants

Grant credits

Adds credits to a prepaid customer’s balance outside checkout: a contract prepayment, a goodwill credit or a promotion. Paid grants carry a cost_basis per credit, which values consumption for revenue and margin; promotional grants have none. Credits are drawn in a published burn-down order: lowest priority first, then soonest expiry, then promotional before paid, then oldest. A grant made here has the expires_at you send, or none. The one-year default is for top-up credits, which come from checkout and auto top-up.

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

The credit type (ID or key). Must match the customer’s prepaid plan.

amountstringRequired
Credits to grant, as a decimal string.
categoryenumRequired

paid credits carry a cost basis and count as deferred revenue until used. promotional credits are free.

Allowed values:
customer_idstringOptional
external_customer_idstringOptional
cost_basisobjectOptional

paid only: what the customer paid per credit. Required for paid grants.

priorityintegerOptional0-100Defaults to 50
Lower numbers are drawn first, inside a pool.
poolstringOptional

The pool (key) the credits join. Default default, or the first pool on the customer’s plan for a grant from checkout.

effective_atdatetimeOptional
When the credits become usable. Defaults to now.
expires_atdatetimeOptional

When unused credits expire. Leave out for no expiry. Only a grant you create here can have none, because top-up credits expire after one year by default.

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 grant.
idstring
object"credit_grant"
customerstring
credit_typestring
amountstring
Credits granted.
remainingstring
Credits not yet drawn, expired or voided.
categoryenum

paid credits carry a cost basis and count as deferred revenue until used. promotional credits are free.

Allowed values:
priorityinteger
effective_atdatetime
statusenum
Allowed values:
sourceenum
What created the grant.
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
cost_basisobjectOptional

An amount of money that can hold fractions of a minor unit, such as a per-token cost.

expires_atdatetimeOptional

When unused credits expire. A top-up or auto top-up grant always has one: one year after payment completes by default, or as the plan’s top_up.credits_expire_in or the checkout session’s credits_expire_in sets. Left out only on a grant created with POST /v1/credit_grants and no expires_at.

source_idstringOptional
The checkout session, subscription, allowance or earlier grant behind it.
poolstringOptional
The pool the credits sit in.
allowancestringOptional

The allowance key behind a grant with source: allowance, or its rollover.

actorobjectOptional
Who created the grant, when a person or agent did.
voided_atdatetimeOptional
void_reasonstringOptional
voided_byobjectOptional
Who voided it.

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