In this article
A balance of 130 credits looks simple until 30 of them expire tomorrow, 100 came from a payment, and a job running in the background has already reserved some of the total. The customer sees one number. The product may be managing several different promises.
Before selling prepaid usage, define what a credit can buy, when it becomes available, which balance is spent first, and what happens when work is corrected. A clear ledger makes those promises visible. It also gives support a way to explain a balance without inventing exceptions one customer at a time.
Treat each grant as a separate promise
A credit grant should retain its origin, eligible usage, effective time, expiry rule and remaining amount. Combining everything into a single mutable total makes it hard to answer a basic question: which purchase or promotion paid for this job?
Stripe’s Credit Grant object distinguishes paid and promotional grants and includes effective time, expiry and priority fields. Those categories are internal tracking fields; a product still needs to explain the balances in language its customers can understand.
Choose the unit carefully. If credits represent a monetary allowance, say what currency and charges they cover. If a credit purchases a task or another service unit, explain how different task types consume it. Do not switch between “credits” and “dollars” in a way that suggests an exchange promise your product does not make.
The following fictional example uses dollar-denominated service credits for one eligible usage category. It illustrates product behavior, without prescribing legal terms, refund rights or accounting treatment.
Follow two balances through a full cycle
Suppose a customer buys $100 of service credits and receives a separate $30 promotional grant. The chosen policy spends eligible promotional credits first. Paid credits do not expire in this example; the promotion expires at a stated timestamp before the next renewal.
Each row below is a posted ledger event, not an in-progress estimate. The application has already established that the usage is eligible and that the amount is final.
| Event | Paid balance | Promotional balance | What the customer can use afterward |
|---|---|---|---|
| Purchase and promotion become effective | $100 | $30 | $130 of eligible usage |
| $20 of eligible usage is posted | $100 | $10 | $110 |
| Remaining promotion expires | $100 | $0 | $100 |
| Another $25 of usage is posted | $75 | $0 | $75 |
| A $5 overcharge in that paid usage is corrected | $80 | $0 | $80 |
| Customer buys a new $100 bundle at renewal | $180 | $0 | $180 |
The final $180 follows from the stated rollover policy. Renewal adds a grant; it does not erase the unused $80. Another product may choose a different policy, but it must show the consequence before customers rely on a balance carrying forward.
The correction also has a specific origin. It reverses $5 of a debit against paid credits. Calling it a new promotion would give the returned value different conditions and could make a later expiry inexplicable.
Define “available” while work is running
A posted balance is insufficient for a product that can start several costly jobs at once. Suppose two jobs check the same balance before either posts its final debit. Each may appear affordable independently even though their combined usage exceeds the remaining allowance.
Choose a reservation policy for that situation. One approach reserves an estimated maximum when a job is accepted, releases unused reserved value when the job completes, and posts the final charge against the appropriate grants. Other approaches can work, but the product needs one coherent rule for concurrent work.
Show the customer the distinction between available credits, reserved credits and completed usage. A failed job should have a defined reservation-release path. If some work remains chargeable after failure, disclose the rule and record the corresponding debit; do not leave an unexplained reservation hanging indefinitely.
Reservations in this example are a proposed application design. They are not a claim that a particular billing provider automatically enforces an application’s real-time usage budget.
Check the billing system’s clock before promising expiry
A daily usage counter and an invoice ledger can consume credits at different times. Stripe’s billing-credit documentation describes credits applying at invoice finalization. Eligibility considers the invoice period end, grant effective and expiry times, currency and available balance. Its billing credits apply to eligible metered subscription items using Billing Meters, rather than every possible charge.
That makes “credits expire at midnight” incomplete as an implementation requirement. Specify whether a job’s eligibility is determined at acceptance, completion, usage occurrence or an invoice boundary. Then verify that the system performing the deduction follows the same rule.
For multiple eligible grants, Stripe’s documented order begins with configured priority, then expiry, followed by further tie-breakers. A simple promise that promotional credits always go first therefore needs to be translated into the actual configuration and checked. Do not assume the category label alone controls every outcome.
Keep the customer-facing policy short, but make the underlying specification precise. Two invoices, a late usage event or a timezone boundary should not cause the team to discover that “expires” meant different things in different systems.
Decide how corrections interact with an expired grant
The easy correction in our ledger returned paid credits that remained valid. A harder case occurs when a promotion funded a job, the promotion expired, and the customer later reports that the job was charged incorrectly.
Define that case before launch. You might restore value into a replacement grant with a new stated expiry, preserve the original restriction, or handle it through another remedy appropriate to the offer. The choice should be explicit and consistent with the promise made when the credits were issued. Do not silently revive every expired balance or silently discard every correction.
Keep a link from the correction to the original usage and grant. Support should see the original debit, the adjustment and the current usable amount as separate records. The same correction request arriving twice must not create two grants.
Also distinguish a usage correction from a payment refund. Returning service credits to a balance does not by itself return money to a card. The product’s history should identify which action occurred and where the customer can use the resulting value.
Make renewal and exhaustion understandable
At renewal, show which grants carried forward, which expired and what was newly purchased. A total can remain unchanged even though the underlying expiry dates have changed. Customers need the next relevant expiry and the amount affected, not a long internal event log.
At exhaustion, choose the behavior deliberately: stop accepting new work, request another purchase, or apply an agreed overage rule. Keep already accepted work separate from new work so a balance transition does not unexpectedly interrupt an operation the product promised to complete.
Test the entire sequence with one ordinary account: purchase, promotional usage, expiry, concurrent work, correction and renewal. The test passes when the customer-visible history and the underlying balances tell the same story. That is the foundation for prepaid pricing people can plan around.
Sources
Something we should clarify?
Suggest a correction


