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

# See how much credit a customer has available to use

Get credit balances using the new list credit balances for a customer operation to see how much credit a customer has to use, and how much credit they've previously used.

---

## What's new?

We added the [list credit balances for a customer operation](https://developer.paddle.com/api-reference/customers/list-credit-balances.md) to the Paddle API. You can use it to see how much credit a customer has available to use, and how much credit they've previously used.

{% api-endpoint method="GET" path="/customers/{customer_id}/credit-balances"  %}

- **customer_id** (string): Unique Paddle ID for this customer entity, prefixed with `ctm_`
{% /api-endpoint %}

## How it works

When you make prorated changes to a subscription, or when you [create a credit](https://developer.paddle.com/build/transactions/create-transaction-adjustments.md) to adjust the amount due on an issued invoice, Paddle creates an adjustment to record the change to a transaction.

Credit balances are totals for credit adjustments for a customer in a particular currency. They hold information about how much credit a customer has available now, and how much they've previously used. They also include the total reserved — this is where credit has been applied to [an issued invoice](https://developer.paddle.com/build/invoices/create-issue-invoices.md) (a manually-collected transaction marked as `billed`) that hasn't yet been fully paid.

You can use the new [list credit balances for a customer](https://developer.paddle.com/api-reference/customers/list-credit-balances.md) operation to see all credit balances for a customer.  

{% callout type="info" %}
Customers typically have one credit balance, but they may have more than one credit balance if they've been credited in multiple currencies. Customers who haven't been credited don't have any credit balances.
{% /callout %}

## Example

A successful response returns an array with an object for each credit balance. Paddle creates and maintains one credit balance for each currency a customer has been credited in.

The `balance` object for each credit balance contains the total `available`, temporarily `reserved` for billed transactions, and `used`.

{% api-example method="GET" path="/customers/{customer_id}/credit-balances" %}

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

{% /api-example %}

## Next steps

This change is available in version `1` of the Paddle API.

It's a non-breaking change, meaning it doesn't impact existing integrations.

Check out [our credit balance guide](https://developer.paddle.com/build/customers/get-customer-credit-balances.md) and the [list credit balances for a customer](https://developer.paddle.com/api-reference/customers/list-credit-balances.md) in the API reference to get started.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| GET List credit balances for a customer | API operation | added | Customers |  |