Research-backed calculator guide

Prepaid AI Credits Ledger: Reserve, Settle, Expire, and Refund Usage Safely

Design a prepaid AI credits ledger that reserves before work, settles measured usage, releases failed holds, and keeps expiry, refunds, and cost attribution auditable.

What the ledger must represent

Start by defining the unit customers buy. It may be an abstract AI credit, a token-like unit, or a currency-denominated wallet. Publish the conversion: for example, “one image request reserves up to 40 credits” or “one credit represents $0.01 of prepaid service value.” Do not silently change that meaning between plans or model versions.

A useful ledger entry has at least:

• entry_id, a unique immutable identifier;
• customer_id, workspace, project, or agent scope;
• entry_type, such as grant, reservation, settlement, release, expiry, refund, or adjustment;
• signed amount in integer credit units, with a documented precision;
• operation_id for the logical customer action;
• payment_reference for a purchase or refund;
• price_version and model or feature code used to calculate the charge;
• provider request or usage IDs, when external usage is involved;
• creation time, effective usage time, and actor or service name;
• a link to the original entry when reversing or correcting it.

“Append-only” means a correction adds a linked entry rather than editing history. Stripe’s customer balance transaction API uses the same useful design principle for its own balance object: it creates an immutable transaction, and amounts are expressed in the smallest currency unit. That is a provider-specific API rule, not a requirement that your AI credits must be denominated in dollars, but it illustrates why immutable movements are easier to audit than overwritten balances. ^[4]

Paid and promotional credits should normally be separate lots. Give each lot its own grant date, expiry policy, refund rule, and price basis. If you use first-expiring-first consumption, record which lot funded each settlement. Chargebee documents grant-level expiry and deduction from the grant expiring soonest in its prepaid-credit model. ^[1] Your own contract may require a different ordering, so make the policy explicit.

Reserve, settle, and release

A request should not begin unlimited chargeable work merely because a delayed meter will report usage later. First estimate the maximum exposure for the operation. That estimate could be a token ceiling, a maximum number of tool calls, an image count, or a capped monetary amount converted into credits.

In one transaction, verify that available balance is sufficient and create a reservation. The invariant is:

available balance = ledger balance − active reservations

When the provider returns measured usage, create one settlement for the logical operation and release the difference between the reservation and actual charge. If the actual charge is greater than the original reservation, either stop at the cap, obtain a second authorization, or apply a separately documented overage rule. Never allow a hidden negative balance simply because the estimate was optimistic.

Separate the logical operation from provider attempts. A timeout can lead to a retry, and a retry can create more than one provider request. Your billing rule should say whether those attempts are one customer operation or separate billable operations. Store both the customer operation and provider attempt IDs so reconciliation can distinguish a retry from a duplicate purchase.

Chargebee exposes both a direct credit-ledger approach and a usage-ingestion approach. Its configuration documentation describes an authorization step for reserving credits before finalizing consumption, and it also warns that asynchronous usage events cannot provide a strict cutoff by themselves. That is why a real-time application gate belongs in front of work that must not exceed a hard limit. ^[2]

Worked cost example

Assume the following illustrative plan. These are calculation assumptions, not a vendor quote:

• The customer prepays $200.
• The product defines 1 credit = $0.01 of prepaid service value, so the grant is 20,000 credits.
• A document-analysis request reserves 1,200 credits.
• Measured usage is 730 credits.
• The estimated provider cost basis is $0.004 per consumed credit.
• There are no taxes, payment fees, support costs, or promotional credits in this simplified example.

The customer has 19,270 credits remaining. The product consumed $7.30 of prepaid value at the stated $0.01 rate. Under the illustrative provider-cost assumption, estimated provider COGS is $2.92, leaving $4.38 of contribution before other costs. Do not present that contribution as gross margin unless you also include the other cost categories your finance policy requires.

The table is also a concurrency control. Suppose two requests arrive when only 2,000 credits are available. Request A reserves 1,200 first. Request B then sees 800 available and must be denied, reduced, queued, or sent through an explicit top-up or overage path. If both requests read 2,000 before either writes a hold, the system can overspend without any arithmetic error in the final settlement. Use a database transaction, atomic conditional update, or an equivalent concurrency-safe mechanism.

Failure, timeout, and refund states

A failed operation should not automatically become a permanent charge, but it should not automatically release a hold while work may still be running. Use an explicit state sequence such as authorized → running → settled, with alternate paths for released, failed, expired, and refunded.

For a provider rejection before chargeable work begins, record the failed attempt and release the entire reservation. For a timeout, first confirm provider status or cancel the job. If the job completed but your callback was lost, import the provider usage record and settle once. If status is genuinely unknown, keep the reservation in a recoverable state and alert an operator or reconciliation worker. Releasing immediately can let the customer spend the same credits twice.

A refund is a policy decision with two different meanings:

1. Credit reversal: return unused or incorrectly charged service value to the customer’s credit wallet. Link the reversal to the original settlement and preserve the original entry.
2. Cash refund: return money through the payment channel, potentially reducing the unearned prepaid balance and requiring a payment, tax, invoice, and accounting adjustment.

Do not call a credit reversal a cash refund. If a customer has used part of a grant, calculate the refundable amount from the contract and the recorded settlement history. The ledger should show the original grant, consumed amount, reversal, and any cash transaction reference.

Payment webhooks and top-ups need idempotency too. Stripe documents idempotency keys as a way to safely retry requests without creating the same object or update twice, and recommends a unique key for the logical request. Apply that idea to your own funding workflow: a payment event should have a unique purchase reference, and a repeated webhook should return the existing grant rather than add credits again. ^[3]

Expiry, rollover, and customer trust

Write expiry rules before selling the credits. Decide whether purchased credits never expire, expire at a fixed date, or roll over under a cap. Promotional credits can have a different expiry, but the distinction must be visible at purchase and in the wallet.

Expiry should be a dated ledger entry against the eligible lot, not a silent deletion. At expiry time, calculate only the unused portion. A reservation attached to a still-running operation should not be expired without a rule for that in-flight work. Likewise, a late usage event must be assigned according to its effective usage time and the applicable grant policy, not whichever grant happens to be current when the event arrives.

Show customers their ledger balance, active holds, available balance, upcoming expiry, recent settlements, and the reason for each change. A balance without a usage history creates support tickets because customers cannot distinguish a completed job from a reservation or an expired promotion.

Cost basis and attribution

A prepaid credit is a customer-facing unit, not necessarily the provider’s cost unit. Preserve the raw provider usage and the conversion used to charge credits. For each settlement, capture model, input and output usage where available, tool or retrieval usage, provider price version, and any retry or fallback relationship. This lets finance recompute estimated COGS when a provider invoice arrives.

Use a separate internal cost view rather than changing historical customer charges whenever provider pricing changes. Historical settlements should retain the price version that governed them. New pricing can use a new version, an effective timestamp, or a plan-specific override.

Attribution also needs an owner dimension: customer, plan, workspace, feature, model, environment, or agent. The FinOps Foundation describes allocation as assigning cost and usage to responsible owners through accounts, tags, labels, hierarchies, and documented shared-cost rules. Apply the same discipline to AI operations: define required metadata before a request is accepted, identify shared infrastructure, and state whether shared costs are allocated proportionally, by a proxy metric, or kept centrally. ^[5]

For a monthly close, reconcile four totals: payment processor funding to credit grants; credit settlements to product operations; provider usage to estimated COGS; and the closing ledger balance to the customer-facing wallet. Investigate any orphaned reservation, settlement without a provider operation, provider usage without a customer operation, negative available balance, or duplicate payment reference.

Implementation checklist

Build the smallest safe version around these controls:

1. Define credit units, precision, lots, pricing versions, expiry, rollover, overage, and refund terms.
2. Grant paid credits only after server-side payment confirmation, with a unique purchase reference.
3. Make reservation creation and available-balance checking atomic.
4. Give every customer operation an idempotent operation ID and every provider attempt its own ID.
5. Settle measured usage once, then release the unused hold in the same transaction where possible.
6. Keep unknown-timeout holds recoverable until provider status is known.
7. Record expiry and refunds as linked entries rather than edits or deletes.
8. Enforce hard limits in the application when downstream usage ingestion is asynchronous.
9. Expose balance, holds, expiry, and transaction history to customers and support staff.
10. Reconcile payments, product events, provider usage, and internal cost attribution on a defined cadence.

For the broader monthly model around agents, staffing, tools, and run costs, use the AI Agent Cost Calculator | Model Full Monthly Spend. When actual provider invoices arrive, the AI API invoice reconciliation calculator can help compare estimated usage with billed rows. If tracing and evaluation volume are part of the operation, compare their economics with the AI observability ROI calculator.

FAQ

What is a prepaid AI credits ledger?

It is an immutable or append-only record of prepaid credit grants and every later movement: reservations, settlements, releases, expiries, refunds, and adjustments. The ledger is not just the current wallet balance. It preserves why the balance changed, which operation caused the change, and which original entry a reversal corrects.

Why reserve credits before an AI request?

Reservation protects against concurrent requests and variable execution cost. If two requests see the same balance and both start work, a delayed usage meter can allow more work than the customer paid for. A reservation reduces available balance immediately. After completion, the system settles measured usage and releases the unused portion.

What should happen when an AI job fails?

Record the failure and release the reservation only after the job is confirmed not to have completed or continued elsewhere. If the provider completed the job but your callback failed, import the provider’s usage record and settle according to the published billing rule. A timeout is an unknown state, not proof that no usage occurred.

Are prepaid credits the same as a cash refund?

No. A credit reversal restores service value inside the wallet. A cash refund returns money through the payment process and may require separate invoice, tax, and accounting treatment. A safe ledger links either action to the original grant or settlement and preserves both the wallet movement and the payment reference.

Should unused AI credits expire?

That depends on the plan and contract. If credits expire, record an explicit expiry entry against the eligible lot, show the date to the customer, and explain whether purchased and promotional credits follow different rules. If credits roll over, define whether rollover is unlimited, time-limited, capped, or subject to another published rule.

Can a billing platform enforce a hard credit limit by itself?

Not necessarily. Chargebee’s documentation says its usage-ingestion path processes events asynchronously and does not reject usage when the balance runs out; it instructs teams to gate access in their application for a limit. Treat vendor behavior as product-specific and test the actual path you deploy. ^{[1] [2]}