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

Never 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 now
  • reserved_units โ€” what is already held by work in flight, and is already excluded from available_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

FieldMeaning
credits_enabledWhether credit enforcement applies to this organisation. See the warning below: a balance can exist while this is false.
available_unitsUnits available to spend. Already net of reserved_units.
reserved_unitsUnits held by open reservations.
plan_keyAlways 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"

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 returns 404 for the duration of that request. A scoped key must also hold organizations:read to use x-acting-as; a key scoped to billing:read alone gets 403 Insufficient scope for x-acting-as from the auth layer.

Errors

StatusMeaning
400The id is not a UUID.
401Missing or invalid API key.
403The key does not hold billing:read โ€” or the request used x-acting-as without organizations:read.
404The organisation is not in this key's scope.
503CREDIT_LEDGER_UNAVAILABLE โ€” the ledger is unreachable. Carries retry-after. Retry; never read it as a zero balance.

Required scope: billing:read