# Customer balance Configure Stripe-authored scripts to customize customer balance behavior. ### Interested in getting early access to Stripe-authored scripts? Enter your email to request access. ```bash curl https://docs.stripe.com/preview/register \ -X POST \ -H "Content-Type: application/json" \ -H "Referer: https://docs.stripe.com/billing/scripts/stripe-authored/customer-balance" \ -d '{"email": "EMAIL", "preview": "scripts_preview"}' ``` Use the following scripts to customize billing behavior for customer balances. > 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 customization 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 behavior, see the descriptions of each [available script](https://docs.stripe.com/billing/scripts/stripe-authored.md#use-cases). ## Minimum amount before collection By default, when a customer has a [balance](https://docs.stripe.com/billing/customer/balance.md), 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 1. Select **Customize** next to **Customer balance**. 2. Select **Minimum amount before collection**. 3. 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 100 USD before collection. 4. 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 30 USD debit balance and receives a 20 USD invoice. The script is configured with a threshold of 100 USD. The total owed would be 50 USD, which is below the threshold, so the invoice is zero-charged and the 50 USD carries to the next cycle. If instead the invoice were 80 USD, the total would be 110 USD, which exceeds the threshold, so the full balance is applied and the customer is charged 110 USD. **Scenario 1: Below threshold** - Invoice total: 20 USD - Customer balance: 30 USD debit - Total owed: 50 USD (below the 100 USD threshold) **Result:** Stripe debits the invoice total of 20 USD to the customer’s balance, which results in a 0 USD amount due for this invoice. No payment is collected this cycle. **Scenario 2: At or above threshold** - Invoice total: 80 USD - Customer balance: 30 USD debit - Total owed: 110 USD (above the 100 USD threshold) **Result:** Stripe applies the full 30 USD balance. The customer is charged 110 USD. New balance: 0 USD. 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 1. Select **Customize** next to **Customer balance**. 2. Select **Maximum credit per invoice**. 3. 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 100 USD of credit can be applied per invoice. 4. 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 500 USD credit balance and receives a 200 USD invoice. The script is configured with a limit of 50 USD. Only 50 USD of credit is applied, so the customer pays 150 USD. The remaining 450 USD in credit stays on the balance for future invoices. **Default behavior** Stripe applies the full 150 USD of available credit to the invoice. - Credit applied: 150 USD - Customer pays: 0 USD - Remaining credit balance: 50 USD **After activating the script** Stripe applies only 100 USD of credit to the invoice. - Credit applied: 100 USD - Customer pays: 50 USD - Remaining credit balance: 100 USD 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. ## See also - [Stripe-authored scripts](https://docs.stripe.com/billing/scripts/stripe-authored.md) - [Configure a script in the Dashboard](https://docs.stripe.com/billing/scripts/configure.md) - [Apply custom balances to invoices](https://docs.stripe.com/billing/scripts/customer-balance.md)