The wallet pattern: prepaid credits done right
Prepaid credits look simple until burn-down, grants, and top-ups collide. A field guide to getting it right.
Credit wallets are the pricing primitive every usage-based product eventually reaches for: customers prepay, usage burns the balance down, and a top-up keeps things moving. The concept is simple. The edge cases are not.
Three kinds of credits, one balance
A wallet usually needs to distinguish paid credits, promotional grants, and trial credits—because they behave differently at expiry and refund time but need to be presented as a single number to the customer.
“A customer should never need a spreadsheet to understand their own balance.”
Burn order matters more than people expect
Burn grants before paid credits. It sounds obvious once stated, but getting it backwards means a customer's paid balance disappears into a promo that was going to expire anyway—and support tickets that follow are hard to explain away.
Top-ups: the moment that actually matters
The top-up flow is the highest-leverage screen in the whole system, because it fires exactly when a customer is about to be blocked from using your product. We settled on three tiers: a threshold alert with a one-click link, an optional auto-charge for customers who opt in, and a hard stop with a clear, non-punitive message if neither fires in time.
Get the wallet right, and it becomes invisible—which, for a piece of billing infrastructure, is the best compliment it can get.