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

# Work with credit balances

See how much credit a customer has to use. Credit balances are automatically used to pay for future transactions or reduce the amount due on issued invoices.

---

When Paddle creates credits for prorated changes to a subscription, credit may be added to a credit balance for a customer.

You can check credit balances for a customer to see how much credit they have and how much they've previously used. Credit balances are automatically used to pay for future transactions or reduce the amount due on issued invoices.

## How it works

Credit balances are stored against [customer entities](https://developer.paddle.com/api-reference/customers/overview.md). They hold information about how much credit a customer has available.

Where customers are billed in [multiple currencies](https://developer.paddle.com/concepts/sell/supported-currencies.md) and receive a credit, Paddle creates a credit balance for each currency. Credit balances can only be applied to transactions in the same currency.

{% callout type="info" %}
Credits in Paddle are always related to existing transactions. [They adjust an amount](https://developer.paddle.com/build/transactions/create-transaction-adjustments.md) that's been paid, or an amount that's due on an issued invoice. They're not promotional credits, which are credits given to customers for things like referral schemes or promotions.
{% /callout %}

### Credits are for prorated subscription changes

When customers make prorated changes to a subscription, it might result in a credit. This is common in downgrade scenarios, where customers [swap to a less expensive plan](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md) or [remove items](https://developer.paddle.com/build/subscriptions/add-remove-products-prices-addons.md) midway through their billing cycle.

When a prorated credit fully pays for a subscription change and there's an amount remaining, Paddle creates a credit balance for a customer to hold what's left.

You can check `details.totals.credit_to_balance` against [the related transaction](https://developer.paddle.com/api-reference/transactions/overview.md) for a subscription change to see how much was added to a credit balance. This is included on invoices sent to customers from Paddle, too.

### Credits are automatically applied

Paddle automatically uses credit balances to pay for future transactions. Each credit balance has three totals:

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

In most cases, credit moves from the `balance` total to the `used` total when applied to a transaction. This is the case when a credit balance fully pays a transaction, or when the remaining balance of a transaction is successfully collected immediately.

However, when a transaction is `billed`, like when [working with an issued invoice](https://developer.paddle.com/build/invoices/create-issue-invoices.md), the credit applied to that transaction moves from the `balance` total to the `reserved` total. It's not available for other transactions at this point, but it's not yet considered used.

When a `billed` transaction is fully paid and marked as `completed`, then the credit moves from `reserved` to `used`. If a `billed` [transaction is `canceled`](https://developer.paddle.com/build/invoices/cancel-invoices.md), `reserved` credit returns to `balance`.

## Before you begin

Credit balances are for customers, so you'll need to [get a customer](https://developer.paddle.com/api-reference/customers/get-customer.md) to work with credit balances for them.

Paddle creates a credit balance for a customer when they first have a credit. An empty `data` array is returned for customers who don't have any credit balances.

## Check credit balances for a customer

You can work with credit balances for a customer using the API.

Send a `GET` request to the `/customers/{customer_id}/credit-balances` endpoint to list credit balances for a customer.

If successful, Paddle responds with a list of credit balances for a customer. An empty `data` array is returned where a customer has no credit balances.

{% accordion %}
{% accordion-item title="Customer with a credit balance for USD" %}

In this example, a customer has a credit balance for `USD`.

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

```json
{
  "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 %}

{% /accordion-item %}
{% accordion-item title="Customer with no credit balances" %}

In this example, a customer has no credit balances.

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

```json
{
  "data": [],
  "meta": {
    "request_id": "2d89f662-842b-4644-8915-3bb289d10912"
  }
}
```

{% /api-example %}

{% /accordion-item %}
{% /accordion %}

## Apply a credit balance to a transaction

Paddle automatically uses credit balances for a customer to pay or part-pay for transactions. You can't work with credits directly.

{% callout type="info" %}
Paddle creates a credit balance for each currency. Credit balances for a currency are only applied to transactions for that currency.
{% /callout %}

You can check `details.totals` against [a transaction](https://developer.paddle.com/api-reference/transactions/overview.md) get a breakdown of any credit applied to a transaction. In particular, `credit` details the total credit applied to a transaction and `grand_total` lets you know the amount due after credits but before any payments.

## Create or add to a credit balance

Paddle automatically creates credits when customers make prorated changes to a subscription, and the changes result in a prorated credit that isn't fully used up on the related transaction for the subscription change. You can't add to a credit balance yourself.

You can [create a credit adjustment for a transaction](https://developer.paddle.com/build/transactions/create-transaction-adjustments.md) to reduce the amount due to pay on an issued invoice. Paddle doesn't add the credited amount to a credit balance because it's immediately applied to the invoice.