Customer credit balance
Learn how to use the customer credit balance.
Every customer in Stripe Billing has a credit balance that you can issue credit and debit adjustments against. Adjustments in the credit 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 credit 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 credit 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 credit balance as a debit. This functionality only occurs for customers without a cash_balance.
Customer credit balance details
Keep the following details in mind when using customer credit balances:
- The credit balance automatically applies toward the next invoice finalized to a customer.
- You can’t choose a specific invoice to apply the credit balance to.
- You can’t choose to not apply the credit balance to an invoice.
- The credit balance is in the customer’s currency.
- Customers with a cash balance can’t keep a positive balance. In other words, they can’t increase the amount due on the next invoice.
- The credit balance doesn’t apply to invoices created by Checkout Sessions with
invoice_
enabled.creation
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 credit balance are recorded as Transactions. After it’s been created, you can only update its description
or metadata
—you can’t edit other properties or delete a transaction.
Undo a transaction
You can only undo it by creating a corresponding, reversing transaction. For example, if you credit the customer 10 USD you would have to 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:
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_ | Traces the application of credit against a linked Invoice. |
credit_ | Traces the creation of credit to a Credit Note and it’s associated Invoice. |
invoice_ | When the amount due on an invoice is less than Stripe’s minimum chargeable amount and the customer does not have a cash balance, the invoice is debited to the credit balance and added to the amount due of the next issued invoice. |
invoice_ | When the amount due on an invoice is greater than Stripe’s maximum chargeable amount and the customer does not have a cash balance, the invoice is debited to the credit balance and added to the amount due of the next issued invoice. |
unapplied_ | Traces the reversal of an applied credit balance from a linked Invoice. Paired with an earlier ‘applied_to_invoice’ transaction. |
unspent_ | When unspent funds in receiver Sources attached to a customer without a cash balance 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’s credit balance when a customer is created using the API with a non-zero credit balance. |
Modify the credit 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 Invoice credit balance panel, and click Adjust balance to display the Credit balance adjustment modal.
From here you can set information about the adjustment, such as the Adjustment type (credit or debit), as well as a Currency (only available if the customer doesn’t have a currency set), Amount, and an internal note (visible to Dashboard users, but not the customer).
API
Create adjustments using the Customer Balance API, as shown in the following code example.
Credit balance transaction history
Audit a customer’s credit balance adjustments in the Dashboard by navigating to a Customer’s detail page and scrolling to the Invoice credit balance panel.
The Invoice credit balance panel displays the current value of the 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 credit balance, or the credit note that credited the balance.
API
Use the Customer Balance List API to retrieve a list of all transactions for a Customer.
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 can’t create a negative customer cash balance since it represents money sent from the
Customer
.You can’t 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 can’t remove a
Customer
’s available balance.