A valid request URL is required to generate request examples{
"customer_id": "9b2f0f6e-1a52-4c8e-9d3a-1f2e3d4c5b6a",
"feature": "tokens",
"amount": 1500,
"balance": 8500,
"overage": 0
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Record usage against a credit balance
One consumption of a credit feature, reported by your backend: the balance is folded, the spend is refused if it would cross the plan’s overdraft floor, and one negative line is written — atomically, so two concurrent spends of one balance cannot both pass.
Fail closed. 402 insufficient_credit means nothing was written; how far below zero a balance may go is the overdraft_limit on the plan’s cell for this feature, and no cell means zero.
Unless the excess is billed. Where the environment’s credit_overage is bill, the plan’s cell names an overage_meter_ref and the connected gateway can report metered usage, a spend past the floor is let through instead of refused: the covered part comes off the balance, the excess is recorded and reported to the gateway to be priced on the next invoice, and the response says how much in overage. All three have to be true — any of them missing and the answer is the same 402 it has always been.
Two idempotency layers, because they answer different replays. The Idempotency-Key header replays this response — status and bytes — for 24 hours, which is what a client’s retry wants. request_key in the body refuses a second line forever (409 request_key_spent), which is what a batch re-run a week later needs: the usage stays recorded once, however many times the job runs.
The customer is resolved within the key’s environment — a live key naming a test customer answers 404 — and the feature travels as the key of your own catalogue, the same string your code gates on.
A valid request URL is required to generate request examples{
"customer_id": "9b2f0f6e-1a52-4c8e-9d3a-1f2e3d4c5b6a",
"feature": "tokens",
"amount": 1500,
"balance": 8500,
"overage": 0
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Autorizações
An organization API key, uk_sk_live_… or uk_sk_test_…. The environment is resolved from the stored key row on every request, never from a request parameter.
Every route behind this credential is rate limited per key — 1000 requests a minute — with a second ceiling of 3000 a minute across all the keys of one environment, so splitting your traffic across keys isolates it and minting more keys does not buy more of it. A test key can never spend a live key's allowance. Every response carries the current state in headers; see the rate-limits guide.
Cabeçalhos
A key you choose — a UUID, or your own identifier for the operation — that makes this write safe to retry. Send the same key again and you get the same response back: the same status, the same body, and Idempotent-Replay: true. The handler does not run a second time.
The key is scoped to your API key and the route, so keys never collide between environments or tenants. It is remembered for 24 hours. Reusing it for a different request is refused (422), and a second request arriving while the first is still running is refused too (409) — retry that one in a moment.
A request that failed with a 5xx or was rate limited leaves the key spendable: retry it with the same key.
255Corpo
The key of the credit feature being spent. A boolean or metered feature answers 422 — neither holds a balance.
How many units this usage spends. Positive; the ledger line is written negative.
x >= 1Whose balance this spends. Exactly one of customer_id or customer_key is required.
A customer-issued key (uk_ck_…) naming the customer instead — the string a caller presented to your surface. Resolved within your key's environment (404 otherwise, revoked included), and its id is stamped on the ledger line for per-key attribution. Exactly one of customer_id or customer_key is required.
This spend's own idempotency handle — an id from your system, such as the job or request that incurred the usage. Optional, but without it a replayed batch double-charges.
Resposta
The usage was recorded.
What remains after this spend. Negative while inside the overdraft.
How much of amount was billed rather than taken from the balance. 0 on every ordinary spend, and always present — so a client can tell "this came out of what they had" from "this will be on their invoice" without knowing how the environment is configured. Non-zero only where credit_overage is bill on the environment, the plan's cell names a meter, and the gateway can count it.