Get customer live credit balance
const url = 'http://localhost:8080/v1/credits/balance/example/live';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url http://localhost:8080/v1/credits/balance/example/live \ --header 'Authorization: Bearer <token>'How much credit the customer has left right now, per currency: the settled balance less the usage no invoice has billed yet in that currency. Use it to decide in your own code whether to keep serving a prepaid customer; Hardcount records usage and never refuses it.
The read aggregates the customer’s usage events for the current period on every call, so its cost grows with the number of events. Poll it on an interval (for example once a minute per active customer) and cache the answer. Do not call it on every request. A top-up shows on the next read.
Not included, so the figure can read high: tax, base fees billed at period end, and amounts due on unpaid invoices. Requires a secret key.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Responses
Section titled “Responses”Live credit balance
A customer’s credit position right now, one entry per currency: every currency the customer holds credit in, and every currency a live subscription will invoice usage in. Amounts in two currencies are never added together.
object
Ordered by currency.
The live position in one currency. balance_cents is the credit the customer can spend in it: the settled ledger balance, which moves only when an invoice, grant, adjustment or expiry is written, less any grant that is past its expiry date and not yet written off. unbilled_usage_cents is the usage of the current period that no invoice has billed yet and that will be invoiced in this currency. estimated_remaining_cents is the first minus the second, never below zero.
object
Settled ledger balance in this currency, less what is left of any grant past its expiry date that the hourly expiry run has not written off yet (an invoice cannot draw on such a grant). Can be negative.
Metered usage that the next invoice of each subscription invoiced in this currency will bill, priced as the period close prices it. Usage that a mid-period threshold invoice already billed is not counted again. After a mid-period plan change each meter is counted for the time a plan carrying it was on the subscription. For a trialing subscription only usage inside its first paid period counts; that period starts at the beginning of the day the trial ends.
balance_cents minus unbilled_usage_cents, floored at zero. To see how far past zero a customer is, subtract the two parts yourself.
When the server computed these figures.
Example generated
{ "customer_id": "example", "balances": [ { "currency": "example", "balance_cents": 1, "unbilled_usage_cents": 1, "estimated_remaining_cents": 1 } ], "computed_at": "2026-04-15T12:00:00Z"}Customer not found in this tenant and mode