Skip to content
Hardcount
Run it locally
Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

Get customer credit balance

GET
/v1/credits/balance/{customer_id}
curl --request GET \
  --url http://localhost:8080/v1/credits/balance/example \
  --header 'Authorization: Bearer <token>'

The customer’s balances, one per currency the customer’s credit ledger holds, ordered by currency. Empty when the customer has no ledger entry.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
customer_id
required
string

Responses

Section titled “Responses”

200

Section titled “200”

Credit balances, one per currency.

Media typeapplication/json
object
data
required
Array<object>

A customer’s credit balance in one currency and where that credit went. Every cent granted is either still in the balance or in one of the totals: total_granted = total_used + total_expired + total_retired + total_deducted + balance_cents.

object
customer_id
required
string
currency
required

The currency of this balance, uppercase. Each credit ledger entry stores its own currency, and credit pays only invoices in that currency. A customer with credit in two currencies has two balances; they are never added together or converted.

string
balance_cents
required
integer format: int64
total_granted
required

Every credit added: grants, positive adjustments, and credit given back when an invoice it was applied to was voided.

integer format: int64
total_used
required

Credit applied to invoices.

integer format: int64
total_expired
required

Credit written off by expiry.

integer format: int64
total_retired
required

Prepaid commit credit taken back because the invoice that funded it was voided or refunded by a credit note.

integer format: int64
total_deducted
required

Credit an operator deducted (a negative adjustment).

integer format: int64

Example generated

{
  "data": [
    {
      "customer_id": "example",
      "currency": "example",
      "balance_cents": 1,
      "total_granted": 1,
      "total_used": 1,
      "total_expired": 1,
      "total_retired": 1,
      "total_deducted": 1
    }
  ]
}

404

Section titled “404”

No customer with this ID in this tenant and mode.

Media typeapplication/json
object
error
object
type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string
code
string
message
string
request_id
string
param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}