Get a customer's credit balance

Returns a customer's invoice credit balance in every currency it has one: proration credits, goodwill credits and overpayments, applied automatically to the customer's next invoices before they're charged or sent (spec §16.11). It isn't the usage wallet. changes lists the latest movements: operator adjustments, credit used by invoices at finalization and credit returned when such an invoice was voided.

At a glance

REST: GET /api/v1/customers/{id}/credit_balance
MCP tool: customers_credit_balance_get
Operation ID: customers.credit_balance.get
Scope: Brand
Permission: customers:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the customers:read scope
Since: M5

Request

Path parameters

Field	Type	Description
`id`	`cus_…` ID	The customer (`cus_…`).

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"credit_balance"`
`customerId`	`cus_…` ID
`livemode`	boolean
`balances`	array of money	One balance per currency the customer ever had credit in (zero included).
`changes`	array of object	The latest changes, newest first (at most 20).
`changes[].ledgerTransactionId`	`txn_…` ID
`changes[].change`	money	Signed: positive added credit, negative used or removed it.
`changes[].reason`	one of `adjustment`, `invoice_applied`, `invoice_voided`, `proration`, `other`	`adjustment` by an operator, `invoice_applied` at finalization, `invoice_voided` when an invoice gave it back, `proration` for a subscription's unused time.
`changes[].memo`	string
`changes[].invoiceId`	`inv_…` ID or null
`changes[].effectiveAt`	date-time

Examples

€50 left after an invoice used €200

HTTP

GET /api/v1/customers/cus_01m4tx5nj8emwbyf7y9vcf47ym/credit_balance
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "credit_balance",
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "livemode": false,
  "balances": [
    {
      "amount": "50000000",
      "currency": "EUR"
    }
  ],
  "changes": [
    {
      "ledgerTransactionId": "txn_01m4tx5nj8emwbyf7y9vcf47yn",
      "change": {
        "amount": "-200000000",
        "currency": "EUR"
      },
      "reason": "invoice_applied",
      "memo": "Invoice GEN-2026-000131",
      "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
      "effectiveAt": "2026-10-20T09:00:00.000Z"
    },
    {
      "ledgerTransactionId": "txn_01m4tx5nj8emwbyf7y9vcf47yq",
      "change": {
        "amount": "250000000",
        "currency": "EUR"
      },
      "reason": "adjustment",
      "memo": "Goodwill for the September outage",
      "invoiceId": null,
      "effectiveAt": "2026-10-20T08:30:00.000Z"
    }
  ]
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`id` isn't a customer ID (`cus_…`).	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such customer in this mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`permission_denied`	403	You can't read this brand's customers (`customers:read`).	Ask an organization owner or admin for a role or scope that allows this action.
`livemode_not_allowed`	403	You have no live-mode access, so you can't use live invoices.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

€50 left after an invoice used €200#

Errors#