> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

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

**List credit balances for a customer**

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.

**Required permissions:** `customer.read`

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_id` | string | required | Unique Paddle ID for this customer entity, prefixed with `ctm_`. (pattern: `^ctm_[a-z\d]{26}$`) |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `currency_code` | array | optional | Return entities that match the currency code. Use a comma-separated list to specify multiple currency codes. |

## Response (200)

- `data`: array (required)
  - `customer_id`: string (required) — Paddle ID of the customer that this credit balance is for, prefixed with `ctm_`. (pattern: `^ctm_[a-z\d]{26}$`)
  - `currency_code`: string (required) — Three-letter ISO 4217 currency code for this credit balance.
    - `USD` — United States Dollar
    - `EUR` — Euro
    - `GBP` — Pound Sterling
    - `JPY` — Japanese Yen
    - `AUD` — Australian Dollar
    - `CAD` — Canadian Dollar
    - `CHF` — Swiss Franc
    - `HKD` — Hong Kong Dollar
    - `SGD` — Singapore Dollar
    - `SEK` — Swedish Krona
    - `ARS` — Argentine Peso
    - `BRL` — Brazilian Real
    - `CLP` — Chilean Peso
    - `CNY` — Chinese Yuan
    - `COP` — Colombian Peso
    - `CZK` — Czech Koruna
    - `DKK` — Danish Krone
    - `HUF` — Hungarian Forint
    - `ILS` — Israeli Shekel
    - `INR` — Indian Rupee
    - `KRW` — South Korean Won
    - `MXN` — Mexican Peso
    - `NOK` — Norwegian Krone
    - `NZD` — New Zealand Dollar
    - `PEN` — Peruvian Sol
    - `PLN` — Polish Zloty
    - `RUB` — Russian Ruble
    - `THB` — Thai Baht
    - `TRY` — Turkish Lira
    - `TWD` — New Taiwan Dollar
    - `UAH` — Ukrainian Hryvnia
    - `VND` — Vietnamese Dong
    - `ZAR` — South African Rand
  - `balance`: object (required) — Totals for this credit balance. Where a customer has more than one subscription in this currency with a credit balance, includes totals for all subscriptions.
    - `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`: object (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.

### Response example

```json
{
  "data": [
    {
      "customer_id": "ctm_01gw9m680k848184fpttwr0b7z",
      "currency_code": "USD",
      "balance": {
        "available": "550",
        "reserved": "900",
        "used": "1300"
      }
    }
  ],
  "meta": {
    "request_id": "32cf1966-ed49-47d6-a76a-a9b8f7843245"
  }
}
```