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 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 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.
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
billedtransactions. - 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, passing the Paddle ID of the customer entity that you want to list credit balances for.
Paddle ID of the customer entity to work with.
Response
If successful, Paddle responds with a list of credit balances for a customer.
In this example, a customer has a credit balance for USD.
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}If successful, Paddle responds with a list of credit balances for a customer.
Paddle creates a credit balance when you take an action that results in a credit, like making prorated changes to a subscription. An empty data array is returned where a customer has no credit balances.
1234561{
2 "data": [],
3 "meta": {
4 "request_id": "2d89f662-842b-4644-8915-3bb289d10912"
5 }
6}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.
Paddle creates a credit balance for each currency. Credit balances for a currency are only applied to transactions for that currency.
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.
Breakdown of the total for a transaction. These numbers can become negative when dealing with subscription updates that result in credit.
Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
Total discount as a result of any discounts applied.
Except for percentage discounts, Paddle applies tax to discounts based on the line item price.tax_mode. If price.tax_mode for a line item is internal, Paddle removes tax from the discount applied.
Total tax on the subtotal.
Total after discount and tax.
Total credit applied to this transaction. This includes credits applied using a customer's credit balance and adjustments to a billed transaction.
Additional credit generated from negative details.line_items. This credit is added to the customer balance.
Total due on a transaction after credits and any payments.
Total due on a transaction after credits but before any payments.
Total fee taken by Paddle for this transaction. null until the transaction is completed and the fee is processed.
Total earnings for this transaction. This is the total minus the Paddle fee. null until the transaction is completed and the fee is processed.
Three-letter ISO 4217 currency code of the currency used for this transaction.
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.
