Skip to main content
POST
Grant credits to a customer

Authorizations

Authorization
string
header
required

Provider secret API key (sk_live_… / sk_test_…) supplied as a Bearer token.

Headers

Idempotency-Key
string

Provider-scoped idempotency key for safe grant retries

Path Parameters

reference
string
required

Customer reference identifier

Example:

"cus_3c4d5e6f7g8h"

Body

application/json
credits
integer
required
Required range: x > 0
reason
string
Maximum string length: 256
Pattern: ^[\p{L}\p{N}\s.,'"&\/()+:%;?!@#_[\]\-]*$

Response

Credits granted successfully

balance
number
required

Customer credit balance after the grant

credits
number
required

Granted credit amount

customerRef
string
required

Customer reference identifier

success
boolean
required

Whether the grant was recorded

reason
string

Machine-readable grant reason