Get Credits
Read an organisation's credit balance.
Use this to show a balance on load, before the caller has selected anything.
โถavailable_units is already net of reserved_units
available_units is already net of reserved_unitsNever add the two together to work out what you can spend. They are two separate figures, not a total and a portion of it:
available_unitsโ what you can spend right nowreserved_unitsโ what is already held by work in flight, and is already excluded fromavailable_units
After a grant of 18 units followed by a reservation of all 18, this endpoint
reports available_units: 0 and reserved_units: 18 โ not 18 and 18.
โถFields
| Field | Meaning |
|---|---|
credits_enabled | Whether credit enforcement applies to this organisation. See the warning below: a balance can exist while this is false. |
available_units | Units available to spend. Already net of reserved_units. |
reserved_units | Units held by open reservations. |
plan_key | Always null on this route, even for an organisation that holds a subscription. Read the plan from GET /organizations/:id/subscription, which reports the real plan_key and its lifecycle. Note this is not the plan field on GET /organizations/me, which is the free/paid billing tier. |
โถcredits_enabled is an enforcement flag, not "has any credits"
credits_enabled is an enforcement flag, not "has any credits"A grant does not turn it on. An organisation that completes a checkout for 18
units reads available_units: 18 with credits_enabled: false, because the
flag is set separately from the grant. Read it as "does credit enforcement
apply", and never infer a zero balance from it.
โถAn organisation with no credits is not an error
A brand-new organisation has no credit history, and this endpoint returns
200 with zeros and credits_enabled: false. Treat that as a valid balance,
not a failure.
A 404 means something different: the organisation id is not one this key
can see. The same status is returned whether the organisation does not exist
or simply belongs to someone else.
โถWhich organisations can I read?
- Your own organisation.
- Any direct child organisation, when you call with a parent organisation's key.
- With
x-acting-as: <child-id>, only that child โ your own balance returns404for the duration of that request. A scoped key must also holdorganizations:readto usex-acting-as; a key scoped tobilling:readalone gets403 Insufficient scope for x-acting-asfrom the auth layer.
โถErrors
| Status | Meaning |
|---|---|
| 400 | The id is not a UUID. |
| 401 | Missing or invalid API key. |
| 403 | The key does not hold billing:read โ or the request used x-acting-as without organizations:read. |
| 404 | The organisation is not in this key's scope. |
| 503 | CREDIT_LEDGER_UNAVAILABLE โ the ledger is unreachable. Carries retry-after. Retry; never read it as a zero balance. |
Required scope:
billing:read