How to Set Up Prepaid Credits Billing

The credit is a conversion layer between money and usage. You set two rates: how much money buys a credit, and how many credits each action costs.

Purchase rate:  1 credit = a fixed amount of money (for example, one cent)
Action costs:   chat message = 5 credits, image = 20 credits, export = 50 credits

Three design rules keep the unit honest.

Make the money value obvious. Stripe warns that the challenge is to make credits pricing feel as intuitive as a dollar amount without making people do mental math. A credit worth a round fraction of your currency is easier to reason about than an arbitrary unit. Some products skip the abstraction entirely and keep the balance in money.

Price actions from cost and value. Lago cautions that a request using an expensive model should not silently have the same credit cost as a cheap one unless your margin can absorb it, and recommends modeling credit burn for light, typical and heavy workloads. Revisit action costs when your own vendor prices change.

Keep the price list short. Stripe notes that if every feature has a different credit cost, you create a cognitive load for customers. A handful of action prices, shown next to the action in the product, works better than a long table on the pricing page.

Version the action costs with effective dates. When you change a price, deductions after the change use the new cost and old deductions remain explainable.

Not all credits are the same, even if the customer sees one balance. Lago separates purchased, included and promotional credits, and recommends treating them as distinct in the ledger because they can have different terms for expiry, rollover and refunds.

Then decide which credits are spent first. Lago shows why this matters: with 2,000 promotional and 10,000 purchased credits, a 9,000-credit month consumes 2,000 free and 7,000 paid credits if promotional credits go first, but 9,000 paid credits if purchased credits go first. The customer sees the same usage, yet the remaining paid balance, the refund exposure and the revenue associated with that month all differ.

A common default is to spend credits that expire soonest first, which usually means promotional and included credits before purchased ones. Whatever you choose, write it in your terms and implement it deliberately rather than relying on whatever order your database returns.

Lago also warns against mixing two different things under one word. A usage credit is spent on actions. A billing credit, or credit note, adjusts an amount owed on an invoice. Label them differently in the product and the books.

The most common implementation mistake is storing the balance as a single number and updating it in place. When a customer asks where their credits went, a single number cannot answer. Lago puts it directly: a wallet needs entries for each paid purchase, free grant, charge, top-up, void, expiry and adjustment, each with a timestamp, source, amount and a reference to the event or invoice it settles.

A minimal schema looks like this:

create table credit_ledger (
  id            uuid primary key,
  account_id    uuid not null,
  entry_type    text not null,   -- purchase, grant, usage, top_up, expiry, refund, adjustment
  credit_type   text not null,   -- purchased, included, promotional
  amount        bigint not null, -- positive adds credits, negative removes them
  money_amount  numeric,         -- cash value for purchases and refunds
  source_ref    text,            -- payment id, invoice id or usage event id
  idempotency_key text unique,   -- prevents double deductions on retries
  expires_at    timestamptz,
  created_at    timestamptz not null default now()
);

The balance is the sum of entries. You can cache it for speed, but the ledger stays the source of truth. Three rules make it reliable:

1. Deduct atomically. Check the balance and write the usage entry in one transaction, so two parallel requests cannot spend the same credits.
2. Use idempotency keys. Give every usage deduction the ID of the action that caused it, so a retried request does not charge twice.
3. Never delete entries. Corrections are new entries that reverse old ones.

Lago describes the payoff: real-time deduction keeps the balance always up to date, so you can block usage or grant credits with confidence. Finance gets a trail from purchase through usage, expiry and refund.

Customers need a way to add credits before they run out. There are three common mechanisms:

• Manual top-up. The customer buys a credit pack when they choose.
• Interval top-up. Credits are granted weekly, monthly or yearly, usually as part of a plan.
• Threshold top-up. When the balance falls below a set level, the system buys more automatically.

Lago distinguishes two kinds of threshold rule. A fixed rule adds a set amount. A target rule refills to a level, for example topping a balance that drops to 20 credits back up to 100. The difference matters to customers: "add 500" always charges the same, while "refill to 500" charges whatever it takes.

Auto-recharge needs guardrails:

• Release credits only after payment succeeds. Metronome's documentation describes payment gating, which gates the release of the balance on successful collection of payment.
• Stop after a failed payment. Metronome notes that when a payment fails with gating enabled, the auto recharge configuration is switched off. Tell the customer and ask them to update their card.
• Cap the frequency and let customers set limits. Limit how many automatic top-ups can run per day, so a runaway script or a stolen account cannot drain a card. Schematic describes adjustable thresholds, refill amounts and monthly spending limits as key auto top-up settings to put in the customer's hands.
• Alert before and after. Lago lists threshold alerts and depletion alerts alongside transaction notifications. Send them to the customer and watch them yourself.

Zero balance. Decide what happens before launch. Lago lists the options: the application can block new work, allow a defined grace or negative-balance amount, start postpaid overage, or require a successful top-up. For short actions, blocking with a clear top-up prompt is usually right. For long-running jobs, check the balance before starting and reserve enough credits, so a job does not fail halfway.

Expiry. Stripe frames the trade-off: if credits last forever, you carry an ongoing liability on your books, but if customers lose money to expired credits, some will leave for good. Lago recommends stating the expiry date at purchase or grant and reminding customers before it arrives. A common, customer-friendly pattern is to let promotional credits expire while purchased credits last much longer. Check with a lawyer or accountant, because some jurisdictions regulate expiry of prepaid value.

Refunds. Decide whether unused purchased credits are refundable, under what conditions and at what value. Record a refund as a negative ledger entry linked to the original payment, so the balance and the cash both reconcile.

Show all three policies on the purchase screen, not only in the terms.

Cash, wallet balance and revenue are three different numbers. Lago states it plainly: cash collection, wallet balance and recognized revenue are separate measures. A purchase brings in cash now, while the service is delivered later as credits are spent.

Under US accounting guidance, Deloitte summarizes the principle: on receiving a prepayment, a company recognizes a contract liability for its obligation to transfer goods or services in the future, and recognizes revenue as it delivers them. In practice, unspent purchased credits sit on the balance sheet as deferred revenue.

Unused credits create a further question called breakage. Deloitte explains that customers may not exercise all of their contractual rights, and the guidance sets out when expected breakage can be recognized as revenue, either in proportion to usage or when the chance of the customer using the rest becomes remote. It also notes that unclaimed property laws may require some amounts to be remitted to a government instead. Zenskar describes how finance teams estimate breakage by analysing historical cohort data on how many credits go unused, which means you need that usage history in a form finance can query.

Promotional credits are another case. Lago observes that promotional credits are not cash receipts, and how they are treated depends on the arrangement. The practical step is the same for all of this: give your accountant a clean ledger, your written expiry and refund policies and your consumption order, and agree on the treatment before your first large prepaid sale. These are judgment calls with real consequences, so check with an accountant rather than choosing a treatment yourself.

Before launch, run this test: create an account, grant promotional credits, buy a pack, spend across several action types, trigger an auto top-up, let a grant expire, issue a partial refund, then reconcile the ledger to the payment processor and the general ledger. If every number ties out, your credits system is ready.