---
title: "List credit balances for a customer"
method: GET
path: "/customers/{customer_id}/credit-balances"
tags: ["Customers"]
---

# List credit balances for a customer

`GET /customers/{customer_id}/credit-balances`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/customers/{customer_id}/credit-balances`
- Auth: HTTP bearer

Returns a list of credit balances for each currency for a customer. Each balance has three totals:

* `available`: total available to use.
* `reserved`: total temporarily reserved for billed transactions.
* `used`: total amount of credit used.

Credit is added to the `available` total initially. When used, it moves to the `used` total.

The `reserved` total is used when a credit balance is applied to a transaction that's marked as `billed`, like when working with an issued invoice. It's not available for other transactions at this point, but isn't considered `used` until the transaction is completed. If a `billed` transaction is `canceled`, any reserved credit moves back to `available`.

Credit balances are created automatically by Paddle when you take an action that results in Paddle creating a credit for a customer, like making prorated changes to a subscription. An empty `data` array is returned where a customer has no credit balances.

The response is not paginated.

## Path parameters

- `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`.

## Query parameters

- `currency_code` string[]

## Response `200`

The request has succeeded.

- object
  - `data` CreditBalance[], required
    - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`.
    - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code.
    - `balance` CustomerBalance, required
      - `available` string, required: Total amount of credit available to use.
      - `reserved` string, required: Total amount of credit temporarily reserved for `billed` transactions.
      - `used` string, required: Total amount of credit used.
  - `meta` Meta, required: Information about this response.
    - `request_id` string, required: Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-07-09** (v1) `e1ac347eb3c5`: 1 breaking, 2 warning
  - added the pattern `^ctm_[a-z\d]{26}$` to the `path` request parameter `customer_id`
  - added the new `CLP` enum value to the `data/items/currency_code/allOf[subschema #1: Currency code]/` response property for the response status `200`
  - added the new `PEN` enum value to the `data/items/currency_code/allOf[subschema #1: Currency code]/` response property for the response status `200`
- **2026-02-02** (v1) `9ba8be0f2006`: 11 breaking, 4 warning, 41 info
  - added the new path request parameter `customer_id`
  - the `data/items/currency_code` response property's maxLength was unset from `3` for the response status `200`
  - the `data/items/currency_code` response property's minLength was decreased from `3` to `0` for the response status `200`
  - the `data/items/balance` response's property type changed from `object` to no type for status `200`
  - …52 more
- **2025-02-03** (v1) `50bbef23e6a1`: 2 info
  - api tag `Customers` added
  - api tag `Adjustments` removed
- **2024-12-06** (v1) `274e5b2be190`: 1 warning, 1 info
  - added the new `VND` enum value to the `data/items/currency_code` response property for the response status `200`
  - added the new optional `query` request parameter `currency_code`
- …earlier changes not shown

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/customers/:customer_id/credit-balances/get.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)