Work with credit balances

When you create a credit for a customer, or when Paddle automatically creates credits for prorated changes, credit may be added to a credit balance for a customer.

You can check credit balances for a customer to see how much they 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 have paid for subscriptions or items in multiple currencies and received a credit, Paddle creates a credit balance for each currency. Adjustments can only be applied to transactions in the same currency.

Credits in Paddle are always related to existing transactions. They adjust an amount 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.

Credit balance lifecycle

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 automatically collected successfully right away.

However, when a transaction is marked as 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.

When a transaction is fully paid and marked as completed, then the credit moves from reserved to used. This is because a billed transaction may be canceled, in which case the credit returns to balance.

Before you begin

Credit balances are for customers, so you'll need to first create a customer.

Credit balances are created when adjustments are created for a transaction for a customer. You can create adjustments, or Paddle may create them automatically when making prorated changes to a subscription.

Check credit balances for a customer

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

Response

If successful, Paddle responds with a list of credit balances for a customer.

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}

Use a credit balance for a transaction

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

Credit balances for particular currency are only used for transactions for that currency.

details.totals against a transaction gives you a breakdown of any credit applied to a transaction:

Add to a credit balance

Create a credit adjustment for a transaction to add to a credit balance for a customer. You can only create credits for manually-collected transactions (invoices) to reduce the amount due.

Paddle automatically creates credits when you make changes to a subscription — like upgrading or downgrading or adding or removing items — and choose to prorate.

Related pages