For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

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.

AI summary

Check a customer's credit balance to see how much prorated credit they have available, and understand how Paddle automatically applies it to future transactions.

  • • Credit balances are created automatically when a prorated subscription change results in a credit that exceeds the cost of the change — you cannot manually add credit to a balance.
  • • Paddle creates a separate credit balance per currency; credit in one currency cannot be applied to transactions in a different currency.
  • • When a transaction is billed, credit moves to reserved until it's completed — if the invoice is canceled, reserved credit returns to balance.

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. They hold information about how much credit a customer has available.

Where customers are billed in multiple currencies and receive a credit, Paddle creates a credit balance for each currency. Credit balances can only be applied to transactions in the same currency.

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 or remove items 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 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, 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, reserved credit returns to balance.

Before you begin

Credit balances are for customers, so you'll need to get a customer 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.

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

GET /customers/{customer_id}/credit-balances
Response (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"
  }
}

In this example, a customer has no credit balances.

GET /customers/{customer_id}/credit-balances
Response (200 OK)
{
  "data": [],
  "meta": {
    "request_id": "2d89f662-842b-4644-8915-3bb289d10912"
  }
}

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.

You can check details.totals against a transaction 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 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.

Was this page helpful?