Private preview

Apply custom balances to invoices Private preview

Use scripts to customize how customer balances are applied to invoices.

Interested in getting early access to customize Billing with scripts?

Enter your email to request access.

Customer balance application scripts allow you to customize how you apply invoice balances, and override the Stripe default behavior. By default, when a customer has a non-zero invoice balance, Stripe automatically applies it to the next invoice—credits reduce the amount due, while debits increase it. This script extension point gives you more control over when and how much of the balance to apply.

Example use cases include:

• Zero-charge customers while adjusting only their balance when specific conditions are met. For example, only charge when the total amount exceeds a threshold.
• Partially apply customer balances based on custom criteria. For example, only apply large debit balances to avoid inconveniencing customers with small charges on large invoices.
• Implement business-specific balance settlement logic that goes beyond the standard automatic application.

Note

You’re responsible for ensuring your configuration is correct. Stripe doesn’t take responsibility for any issues that arise as a result of your configuration.

In preview, if your script raises an error (for example, returns an invalid result, throws an exception, or times out), Stripe defaults to standard functionality for the operation that caused the failure. If your script encounters a large volume of errors or causes harm, Stripe may disable the script and default to standard functionality for all operations.

Customize how you apply balances

With the standard customer balance behavior, Stripe automatically applies the full balance to each invoice. This extension point gives you control over balance application, allowing you to:

• Choose whether to apply the balance to specific invoices.
• Apply only a portion of the balance based on your business rules.
• Implement conditional logic that determines when to settle balances.
• Defer charges until accumulated balances reach a threshold.

Your script receives the invoice total and current customer balance, then returns how much of that balance to apply, which gives you control over the balance settlement workflow.

Stripe-authored scripts

To get you started, Stripe has authored two scripts that address common customer balance application customizations:

• Minimum amount before collection : Stripe defers the amount owed as a debit to the customer balance when the total is below the default minimum charge amount . With this script, you can set a new minimum amount threshold an invoice must surpass to result in collection.
• Maximum credit per invoice : By default, Stripe automatically applies the full customer balance to each invoice. This script allows you to put a limit on how much credit you can apply from the customer’s balance toward an invoice.

Author your own script

To further customize customer balance application behavior, you can author your own script in a subset of TypeScript.

Verify your script

You’re responsible for verifying that your script reflects your intended functionality. Make sure you don’t enter any proprietary information, confidential information (for example, PII), or malicious code.

Before you begin

Before implementing a custom balance application script, learn how customer balances work in Stripe Billing. Understanding debits, credits, and how balances affect invoices helps you design effective custom logic.

For an introduction to scripts and how to deploy them, see the Scripts overview.

See also:

• Customer balance guide
• Customer Balance Transactions API
• Invoice finalization

In addition the global limitations for user-authored scripts, customer balance application scripts have the following limitations:

• API requests to Invoice Line Items Update and Bulk Update will return 4xx error codes if you activate a customer balance application script on your account and the invoice contains line items with tiered pricing .

Example implementation

This example implements the Custom charge threshold logic. Only charge customers when the total amount (invoice plus balance) exceeds a threshold. Below the threshold, you don’t charge the invoice, and we add the full amount to the customer’s balance for the next billing cycle.

Minimum amount before collection script

Implementation considerations

Consider these key points when implementing threshold based balance behavior.

1. Calculate the total owed : Sum the invoice total and customer balance to determine what the customer would owe if the full balance were applied.
2. Handle currency mismatches : Always verify that currencies match between the invoice, balance, and threshold. Fall back to default behavior when they don’t.
3. Apply correct sign conventions : Negative values create credits that reduce the invoice amount, positive values apply debits that increase it.
4. Preserve invoice total : When zero-charging below a threshold, apply a credit equal to the negative invoice total to bring the charge to zero.
5. Configuration flexibility : Use a configuration object to make thresholds and other parameters adjustable without code changes.

How this example works

Scenario 1: Below threshold

• Invoice total: 20 USD
• Customer balance: 30 USD debit
• Threshold: 100 USD
• Total owed would be: 50 USD

Since 50 USD is below the 100 USD threshold:

• Apply -20 USD (a credit equal to the invoice total)
• Customer is charged: 0 USD
• New customer balance: 50 USD (to be charged next billing cycle)

Scenario 2: At or above threshold

• Invoice total: 80 USD
• Customer balance: 30 USD debit
• Threshold: 100 USD
• Total owed would be: 110 USD

Since 110 USD meets the threshold:

• Apply the full 30 USD debit balance
• Customer is charged: 110 USD
• New customer balance: 0 USD

Extension method

Implement the computeAppliedCustomerBalance function to define your custom balance application logic:

Function signature

export default class MyCustomerBalanceApplicationExtension
 implements Billing.CustomerBalanceApplication<CustomerBalanceApplicationConfig> {
 computeAppliedCustomerBalance(
 input: Billing.CustomerBalanceApplication.CustomerBalanceApplicationInput,
 config: CustomerBalanceApplicationConfig,
 context: Context,
 ): Billing.CustomerBalanceApplication.CustomerBalanceApplicationResult {
 // ...
 }
}

Parameters

Returns

Input and output types

Input type

Input types

export interface CustomerBalanceApplicationInput {
 totalAmount: MonetaryAmount;
 customerBalance: MonetaryAmount;
}

export interface MonetaryAmount {
 amount: Decimal;
 currency: Currency;
}

Field descriptions

Example input

Sample request

{
 "totalAmount": {
 "amount": 5000,
 "currency": "usd"
 },
 "customerBalance": {
 "amount": 1000,
 "currency": "usd"
 }
}

In this example:

• The invoice total is 50 USD (5000 cents).
• The customer has a debit balance of 10 USD (1000 cents), meaning they owe you money.

Output type

Output types

export interface CustomerBalanceApplicationResult {
 appliedCustomerBalance: MonetaryAmount;
}

Field descriptions

Automatic balance adjustment

Stripe automatically ensures that the total amount charged to the customer remains correct by adjusting the customer balance accordingly. Your script only needs to return how much balance to apply. The system handles the accounting to conserve the balance.

Example output

Sample result

{
 "appliedCustomerBalance": {
 "amount": 1000,
 "currency": "usd"
 }
}

In this example:

• Apply the full 10 USD debit balance to the invoice.
• You charge the customer 60 USD total (50 USD plus 10 USD).

Test your script

Before deploying your script to production:

1. Test in a sandbox with various invoice amounts and customer balance scenarios.
2. Verify that currency handling matches your expectations.
3. Confirm that the script handles edge cases (zero balances, mismatched currencies).
4. Review the customer balance transaction history to make sure adjustments are recorded correctly.

Data validation requirements

Your script must meet these requirements to execute successfully. Violations result in a validation error.

• Return a CustomerBalanceApplicationResult with both amount and currency on every invocation.
• The currency in appliedCustomerBalance must match the invoice currency.
• A debit application must be less than or equal to the available debit balance.
• Negative applications are allowed only on positive invoices and can’t exceed the invoice amount.

Best practices

We recommend the following best practices when you’re authoring your own custom logic:

• Handle currency mismatches : Always check that currencies match between the invoice and customer balance. Fall back to default behavior when they don’t.
• Respect sign conventions : Positive values apply debits (increase invoice amount), negative values apply credits (reduce invoice amount).
• Test edge cases : Verify that your logic handles zero balances, negative balances (credits), and balances that exceed the invoice total.
• Document your logic : Add comments explaining your balance application rules for future maintainers.

Next steps

• Learn more about scripts
• See the Stripe Billing Extensions repository on GitHub for additional examples