Customer credit balance

Learn how to use the customer credit balance.

Every customer has a credit balance. You can use this to issue a credit adjustment (meaning you owe them money) or a debit adjustment (meaning they owe you money). These adjustments sum up to a balance on the customer that you can apply to future invoices.

Because Stripe computes the customer balance 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 Invoice), or even metadata for your own reference.

Examples

Some common use cases for customer credit balances include:

Issuing a Credit Note to create a credit that reduces the amount due on the next invoice.
Marking an invoice as paid and moving the amount owed to the customer balance as a debit. This happens when the amount due on an invoice is less than the minimum chargeable amount.

Working with credit balances

Keep the following in mind when working with credit balances:

The credit balance automatically applies to the next finalized invoice to a customer.
You can’t choose a specific invoice to apply the credit balance to.
You can’t apply the credit balance to an invoice.
The credit balance is in the Customer’s currency.

Credits and debits

Credits are negative values (a reduction in the amount the customer owes) that you can apply to the next invoice.

Debits are positive values (an increase in the amount the customer owes) that you can apply to the next invoice.

Transactions

All modifications to the credit balance are recorded as Transactions. After you create a transaction, you can only update its description or metadata–you can’t edit other properties or delete it.

Undo a transaction

You can only undo it by creating a corresponding, reversing transaction. For example, if you credit the customer 10 USD, you’d have to debit them 10 USD in a new transaction, each canceling the other one 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:

Type	Description
`adjustment`	An explicitly created adjustment transaction to debit or credit the credit balance. This is the only type of transaction that you can create using API integrations and the Dashboard.
`applied_to_invoice`	Traces the application of credit against a linked Invoice.
`credit_note`	Traces the creation of credit to a Credit Note and its associated Invoice.
`invoice_too_small`	When the amount due on an invoice is less than Stripe’s minimum chargeable amount, the invoice is debited from the customer balance and added to the amount due on the next invoice.
`invoice_too_large`	When the amount due on an invoice is greater than Stripe’s maximum chargeable amount, the invoice is debited from the customer balance and will be added to the amount due on the next invoice.
`unspent_receiver_credit`	When unspent funds in receiver sources aren’t fully charged after 60 days, Stripe automatically charges them on your behalf and credits your balance. When this happens, Stripe also creates a corresponding credit transaction.
`initial`	Represents the starting value of the customer balance when a customer is created via the API with a non-zero credit balance.

Modify the customer balance

You can modify a customer’s credit balance through the Dashboard by creating a new Customer Balance Transaction adjustment from the Customer’s detail page.

Scroll down to find the Customer credit balance panel, and click Add balance adjustment to display the Customer balance adjustment modal.

From here you can set information about the adjustment, such as the Adjustment type (credit or debit), a Currency (only available if the customer doesn’t have a currency set), an Amount, and an internal note (visible to Dashboard users, but not the customer).

Adding a new customer balance transaction adjustment

API

Create adjustments via the Customer Balance API, as shown in the following code example.

Terminal

curl https://api.stripe.com/v1/customers/cus_4fdAW5ftNQow1a/balance_transactions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=-500 \
  -d "currency"="usd"

Customer balance transaction history

Audit a Customer’s balance adjustments in the Dashboard by navigating to a Customer’s detail page and scrolling to the Customer credit balance panel.

The Customer balance panel displays the current value of the customer credit balance, and clicking View details shows you 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 customer’s credit balance, or the credit note that credited the customer’s balance.

Viewing the customer balance transaction history

API

Use the Customer Balance List API to retrieve a list of all transactions for a Customer.

Terminal

curl https://api.stripe.com/v1/customers/cus_4fdAW5ftNQow1a/balance_transactions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: