Private preview
Customer balance Private preview
Configure Stripe-authored scripts to customise customer balance behaviour.
Interested in getting early access to Stripe-authored scripts?
Enter your email to request access.
Use the following scripts to customise billing behaviour for customer balances.
Note
You’re responsible for making sure your configuration is correct. Stripe doesn’t take responsibility for any issues that arise as a result of your configuration.
In preview, if customisation fails for any reason or causes harm, Stripe reserves the right to default to standard functionality and/or pause subscription processing. To understand the default behaviour, see the descriptions of each available script.
Minimum amount before collection
By default, when a customer has a balance, Stripe applies the full amount to the next invoice. This script lets you set a minimum charge threshold. When the total owed (invoice total plus customer balance) is below the threshold, Stripe negates the invoice’s total amount due by deferring the amount to the customer’s balance for the next billing cycle. When the total meets or exceeds the threshold, Stripe applies the full balance and collects payment.
Use this script to avoid collecting on small invoices by deferring them to the customer balance until the total owed reaches a threshold you define. Use it when you want to accumulate charges across billing cycles before collecting, or avoid charging customers for small amounts.
Configuration options
In the Dashboard, go to Settings > Billing > Billing customisations.
- Select Customise next to Customer balance .
- Select Minimum amount before collection .
- Set the Minimum amount , which is the minimum amount (in the currency’s minor unit) the total owed must reach before Stripe collects payment. For example, setting 10000 in USD means the total must reach US$100 before collection.
- Select Save and confirm activation.
Example
Configure this script with a threshold amount and currency. When the total owed (invoice amount plus customer balance) is below the threshold, the invoice is zero-charged and the full amount rolls to the customer balance for the next billing cycle. When the total meets or exceeds the threshold, the full customer balance is applied and the customer is charged.
In this example, a customer has a US$30 debit balance and receives a US$20 invoice. The script is configured with a threshold of US$100. The total owed would be US$50, which is below the threshold, so the invoice is zero-charged and the US$50 carries to the next cycle. If instead the invoice were US$80, the total would be US$110, which exceeds the threshold, so the full balance is applied and the customer is charged US$110.
Scenario 1: Below threshold
- Invoice total: US$20
- Customer balance: US$30 debit
- Total owed: US$50 (below the US$100 threshold)
Result: Stripe debits the invoice total of US$20 to the customer’s balance, which results in a US$0 amount due for this invoice. No payment is collected this cycle.
Scenario 2: At or above threshold
- Invoice total: US$80
- Customer balance: US$30 debit
- Total owed: US$110 (above the US$100 threshold)
Result: Stripe applies the full US$30 balance. The customer is charged US$110. New balance: US$0.
To see the change in the Dashboard, review the invoice after the billing cycle runs. On the invoice detail page, check the line items and the customer balance transaction to confirm whether the charge was collected or deferred.
Maximum credit per invoice
By default, Stripe applies the full customer credit balance to each invoice, reducing the amount due. This script lets you configure a maximum amount of credit that can be applied to a single invoice. Any remaining credit stays on the customer’s balance for future invoices.
Use this script when you want to spread credits across multiple billing cycles instead of applying them all at once, or when business rules require limiting credit usage per invoice.
Configuration options
In the Dashboard, go to Settings > Billing > Billing customisations.
- Select Customise next to Customer balance .
- Select Maximum credit per invoice .
- Set the Maximum credit amount , which is the maximum amount of credit (in the currency’s smallest unit) that can be applied to a single invoice. For example, setting 10000 in USD means at most US$100 of credit can be applied per invoice.
- Select Save and confirm activation.
Example
Configure this script with a maximum credit amount and currency. When a customer has a credit balance, the script caps how much of that credit can be applied to a single invoice.
In this example, a customer has a £150 credit balance and receives a £200 invoice. The script is configured with a limit of £100. Only £100 of credit is applied, so the customer pays £100. The remaining £50 in credit stays on the balance for future invoices.
Default behaviour
Stripe applies the full US$150 of available credit to the invoice.
- Credit applied: US$150
- Customer pays: US$50
- Remaining credit balance: £0
After activating the script
Stripe applies only US$100 of credit to the invoice.
- Credit applied: US$100
- Customer pays: £100
- Remaining credit balance: US$50
To see the change in the Dashboard, review the invoice after the billing cycle. Check the customer balance transaction on the invoice detail page to confirm how much credit was applied.