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 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.
Paddle ID of the customer entity to work with.
API
List customers by making a GET request to the /customers
endpoint. Work your way through the results to find the customer that you'd like to work with.
Dashboard
Head to Paddle > Customers, click the … menu next to the customer in the list, then choose Copy ID.
Response
If successful, Paddle responds with a list of credit balances for a customer.
123456789101112131415161{
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:
total | Total after discount and tax. |
credit | Total credit applied to this transaction. |
grand_total | Total amount to pay on a transaction after credits. |
balance | Total due on 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.