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.

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.

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
1{
2  "data": [
3    {
4      "customer_id": "ctm_01gw9m680k848184fpttwr0b7z",
5      "currency_code": "USD",
6      "balance": {
7        "available": "550",
8        "reserved": "900",
9        "used": "1300"
10      }
11    }
12  ],
13  "meta": {
14    "request_id": "32cf1966-ed49-47d6-a76a-a9b8f7843245"
15  }
16}

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.

Learn more