Sign in
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Customers
Customer Credit Balance
Customer Tax IDs
Products and Prices
Tax Rates
Customer portal
Quotes
Start with a use case
Subscriptions with Checkout
Fixed-price subscriptions with Elements
Metered billing with Elements
Per-seat billing with Elements
Manage subscriptions
How subscriptions work
Subscription webhooks
Change subscriptions
Strong Customer Authentication (SCA)
Improved tax support
Invoices API updates
Migrating to Prices
Additional features
Testing
Add payment methods
Bacs Direct Debit in the UK
BECS Direct Debit in Australia
SEPA Direct Debit in the EU
Invoice customers
How invoices work
Create an invoice
Customize invoices
Hosted invoice page
Additional features
Revenue recognition
Overview
Reports
Methodology
Examples
Overrides
Testing
Subscriptions and invoices
Customers
Customer Credit Balance
billing
·
HomePaymentsSubscriptions and invoicesCustomers

Customer credit balance

How to use the customer credit balance

Every customer in Stripe Billing has a credit balance against which you can issue credit and debit adjustments. 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 which can be applied to future invoices.

Because the customer 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 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.
  • 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 customer balance as a debit.

Good to know

  • The credit balance is automatically applied towards the next invoice finalized to a customer.
  • You cannot choose a specific invoice to apply the credit balance to.
  • You cannot choose to not apply the credit balance to an invoice.
  • The credit balance is in the Customer’s currency.

Debits and credits

Negative values are treated as a credit (a reduction in the amount owed by the customer) which can be applied to the customer’s next invoice.

Positive values are treated as a debit (an increase in the amount owed by the customer to you) which can be applied to the customer’s next invoice.

Transactions

All modifications to the credit balance are recorded as Transactions. Once created, you may only update its description or metadata–you cannot edit other properties or delete a transaction.

Undo a transaction

You can only undo it by creating a corresponding, reversing transaction. For instance, if you credit the customer $10 you would have to debit the customer $10 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:




TypeDescription
adjustmentAn explicitly created adjustment transaction to debit or credit the credit balance. This is the only type of transaction that can be created via API integrations & the Dashboard.
applied_to_invoiceTraces the application of credit against a linked Invoice.
credit_noteTraces the creation of credit to a Credit Note and it’s associated Invoice.
invoice_too_smallWhen the amount due on an invoice is less than Stripe’s minimum chargeable amount the invoice is debited to the customer balance and will be added to the amount due of the next issued invoice.
invoice_too_largeWhen the amount due on an invoice is greater than Stripe’s maximum chargeable amount, the invoice is debited to the customer balance and will be added to the amount due of the next issued invoice.
unspent_receiver_creditWhen unspent funds in receiver sources are not 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.
initialRepresents 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 the Add balance adjustment button to display the Customer 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 does not yet have a currency set), 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 will bring you to 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 which 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
Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Examples
Good to know
Debits and credits
Transactions
Modify the customer balance
Customer balance transaction history