See how much credit a customer has available to use

What's new?

We added the list credit balances for a customer operation 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.

How it works

When you make prorated changes to a subscription, or when you create a credit 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 (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 operation to see all credit balances for a customer.

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.

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

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 and the list credit balances for a customer in the API reference to get started.