Stripe Customer Cash Balance

Two things called a customer balance, and only one of them is money

Stripe draws the line itself. Its documentation opens by saying that your customers might have associated balances containing two types of funds, cash and credit, and then separates them.

The cash balance is money. It arrived by bank transfer, it is available for payment, and Stripe will let you return it to the customer's bank account.

The other one is an invoicing construct. Stripe describes it this way: "In contrast to a cash balance, an invoice balance is an Invoices feature that represents liability between you and the customer." The operative restriction follows immediately: "You can't use invoice balance funds for payment, but you can apply them to offset future invoices." You change it by creating a Customer Balance Transaction adjustment, which is a bookkeeping entry rather than a movement of funds.

That difference decides the accounting question before you ask it. Money in a cash balance is money you are holding for somebody. A credit on the invoice balance is an obligation you have taken on. They are not the same amount, they are not the same account, and one of them exists only inside Stripe's invoicing logic.

The naming does not help. In older Stripe material and in a lot of community writing, credit balance is the term used for what the current documentation calls the invoice balance. If you are reading anything about customer balances, check which of the two the writer means before you act on it.

A reconciliation layer, not a wallet

It is tempting to read the cash balance as stored value, and Stripe closes that door explicitly.

First, you cannot fill it on purpose: "You can't add funds to the customer cash balance directly. This isn't a balance that customers can top up." Money only arrives as a side effect of a bank transfer that was not matched, or of an overpayment.

Second, it is limited in what it can do. Stripe says the balance is "only there as a reconciliation layer" and that "it's not a digital wallet or e-money", adding that "You can't use the cash balance for any other purpose besides future payments, or returns to the customer it's associated with". You cannot move it to a different customer, and you cannot convert it into general Stripe balance on a whim.

Third, it is per currency. Stripe: "A customer can have cash balances in all currencies that you accept bank transfer payments in, each with its own funding instruction." A customer who has wired you euros and pounds has two separate pots that do not offset each other, and listing changes for that customer returns transactions across all of the currencies at once.

That framing is the useful one for anybody reconciling. A cash balance is not a product feature you are offering. It is the holding pen Stripe uses for money that arrived without instructions.

The ledger: what actually moves a cash balance

Every change is a cash balance transaction with a type, and the type list is the clearest description of the object's whole lifecycle. Stripe documents nine of them.

Money in. funded means the customer made a bank transfer. Stripe notes these funds "might be automatically applied to PaymentIntents and invoices depending on the reconciliation procedure", and that when they are, you also see an applied_to_payment transaction.

Money applied. applied_to_payment is funds leaving the cash balance to pay a PaymentIntent, either automatically after funding arrives or through manual reconciliation.

Money coming back. unapplied_from_payment happens when a partially funded PaymentIntent is modified or cancelled and the funds return to the balance. refunded_from_payment is a successful PaymentIntent refunded to the cash balance rather than to a card or a bank account. In both cases Stripe says you can use the funds for future payments.

Money leaving for the customer. return_initiated is unspent funds heading back to the customer's bank account. return_canceled is that attempt being called off, either because you cancelled the refund before the customer submitted bank details or because Stripe could not collect those details.

The two ACH types are the ones worth reading twice, because they are the reason a cash balance is not a settled number. funding_reversed is funds "debited from the cash balance due to an ACH reversal". adjusted_for_overdraft is funds returned to the balance after an ACH reversal drove it negative. A cash balance can go negative and then be corrected, which is not the behaviour most people assume of a pot of money.

And one type changes ownership. transferred_to_balance is money moved out of the cash balance and into your Stripe balance "due to failed refunds or insufficient refund details". That is the point at which funds stop being the customer's money held by Stripe and start being yours.

Reading it, and spending it

The cash balance is not returned on a Customer by default. Stripe's instruction is to retrieve the Customer and expand the cash_balance field, which gives you an available map keyed by currency, plus a settings object.

That settings object carries one field worth knowing about: reconciliation_mode, which is automatic in Stripe's own example and by default. Automatic means Stripe tries to match incoming transfers against what you are owed. Manual reconciliation is available per customer and stops that matching, leaving every application of funds as a deliberate act. Which mode a customer is in changes whether an unexpected credit against an invoice is a feature or a bug, so it is the first thing to check when the behaviour surprises somebody.

Spending a cash balance is a normal PaymentIntent with an unusual payment method type. Stripe: "When your customer has a cash balance, you can use the funds immediately to make a payment up to the available amount", by creating a PaymentIntent with the customer_balance type. The rule is binary: "The payment succeeds if the cash balance has sufficient funds, and fails otherwise." There is no partial draw and no automatic top up, though Stripe points you at bank transfer funding to collect the difference.

One practical note for anyone building reports. The Dashboard shows a customer's balance in the Payment methods section of the Customer page, and the remaining balances view is where unreconciled money becomes visible as a list rather than as a surprise.

Why it matters for your books before anybody spends it

A cash balance sits in an awkward accounting position, and the awkwardness is genuine rather than a gap in anybody's tooling.

The money is inside Stripe. It is not in your Stripe balance and it will not be paid out to you. It is attached to a customer, and the two ordinary endings are that it pays one of their future invoices or that it goes back to their bank. Under either ending, no revenue of yours was created by the transfer arriving.

So the sale is not complete when the money lands. An invoice that a customer wired money for stays open until the funds are matched to it, and until that happens your accounts receivable and your Stripe activity disagree by exactly the unmatched amount. That is correct rather than broken, and it is the reason a customer insisting they paid can be right at the same time as an invoice being genuinely unpaid.

The long-tail ending is different, and it is the one that produces a QuickBooks record. When funds sit unreconciled for long enough, Stripe stops holding them for the customer and moves them to your balance. That movement, and its accounting treatment, is covered in full in the unreconciled payments guide linked below, along with the timeline that leads to it.