Customer invoice balance

Every customer in Stripe Billing has an invoice balance that you can issue credit and debit adjustments against. Adjustments in the invoice balance could be a credit (meaning you owe them money) or a debit (meaning they owe you money). These adjustments sum up to a balance on the customer that you can apply to future invoices.

Because the invoice balance is computed from a ledger an immutable list of debit and credit transactions it provides an audit trail of transactions for the customer. These Customer Balance Transactions can refer to the object related to the adjustment (such as a Credit Note or Customer), or even metadata for your own reference.

Example use cases

Some common use cases for customer invoice balances include:

• Issuing a Credit Note to create a credit that reduces the amount due on the next invoice.
• Prorations from downgrading a subscription can indirectly create credits to reduce the amount due on the next invoice.
• When the amount due on an invoice is less than the minimum chargeable amount the invoice is marked as paid and the amount owed moved to the invoice balance as a debit. This functionality only occurs for customers without a cash_balance.

Customer invoice balance details

Keep the following details in mind when using customer invoice balances. By default:

• The invoice balance automatically applies to the next invoice finalized for the customer.
• A credit invoice balance is applied up to the invoice total amount.
• A debit invoice balance applies the full balance to the invoice.

You can customize how customer balance applies to invoices using customer balance application scripts.

The following constraints apply to customer balances:

• The invoice balance and the invoice currencies must match.
• Customers with a cash balance must maintain a zero or negative balance. The invoice balance can only reduce the amount due on the next invoice.
• The invoice balance doesnt apply to invoices created by Checkout Sessions with invoice_creation enabled.
• Invoice balances apply to new invoices only. If you edit an open invoice, any invoice balance is applied to the invoice revision.

Debits and credits

Negative values are treated as a credit (a reduction in the amount owed by the customer) that you can apply to the next invoice.

Positive values are treated as a debit (an increase in the amount owed by the customer to you) that you can apply to the next invoice.

Transactions

All modifications to the invoice balance are recorded as Transactions. After its been created, you can only update its description or metadatayou cant edit other properties or delete a transaction.

Undo a transaction

You can only undo a transaction by creating a corresponding, reversing transaction. For example, if you credit the customer 10 USD, you must debit the customer 10 USD in a new transaction, each canceling the other out.

Transaction types

All Transactions created with the API or in the Dashboard have a type value of adjustment, representing a debit or credit manually created by you for the customer.

The type property has many more possible values to represent the creation source and reason for the transaction. The following table outlines and describes each of these type values:

Modify the invoice balance

Dashboard

API

You can modify a customer invoice balance in the Dashboard by creating a new Customer Balance Transaction adjustment from the customer details page.

Under Customer invoice balance, click Adjust balance to display the Credit balance adjustment modal.

You can set information about the adjustment, such as:

• Adjustment type: Choose credit or debit
• Currency: Available only if the customer doesnt have a currency set
• Amount
• Internal note: Visible to Dashboard users, but not to the customer

[How to adjust a customer's subscription balance.]

Invoice balance transaction history

Dashboard

API

Audit adjustments to a customer invoice balance in the Dashboard on their customer details page, under Customer invoice balance.

This section displays the current value of the invoice balance. Click View details to see the transaction history used to calculate that value. Each transaction line displays information relevant to the transaction type, such as a link to the invoice that applied the invoice balance, or the credit note that credited the balance.

[Viewing the invoice balance transaction history]

Customer cash balances

Customers using the bank transfers payment method have a cash balance object with one or more currencies in the available object. You can use the funds to make payments or pay invoices.

Customers with available balances have the following behavior:

• You cant create a negative customer cash balance since it represents money sent from the Customer.
• You cant finalize a too-small or too-large invoice with the cash balance (for example, creating a subscription for 0.01 USD). Learn more about minimum and maximum amounts.
• You can delete Customers that have a cash balance, but only if their cash balance is 0.
• You cant remove a Customers available balance.