Use an append-only double-entry ledger with separate authoritative accounts or subledgers for customer-funded value and promotional value. Every grant and debit should retain its source, terms, and balance bucket; a combined “available balance” may be shown to users, but it should be calculated from the separate accounts rather than stored as the sole source of truth. This pattern reduces ambiguity, supports reconciliation, and preserves the different economic identities of funded and promotional credits.
The short answer: maintain separate authoritative accounts in an immutable double-entry ledger
The core design principle is separation by account, not merely by label. Customer-funded value and promotional value should have distinct account identifiers and journal paths from issuance through consumption, expiration, refund, or reversal.
A practical operational ledger might include:
- A customer-funded balance account for value associated with customer payments.
- A promotional balance account for credits issued without a corresponding customer payment.
- Funding, promotional-issuance, usage, expiration, refund, and adjustment transaction types.
- Clearing or control accounts that keep each journal transaction balanced.
- A derived available-balance view for customer-facing display and authorization decisions.
The exact account names and counteraccounts depend on the system and its accounting design. Operational ledger accounts also should not be assumed to correspond one-to-one with financial-statement accounts.
A simplified conceptual flow is:
- Payment record → funded-value journal path → funded balance.
- Campaign authorization → promotional-issuance journal path → promotional balance.
- Metered usage event → explicit depletion policy → bucket-specific debit.
- Funded balance + eligible promotional balance → derived available balance.
Each journal transaction should balance, carry a stable identifier, and remain append-only. If an event is incorrect, the system should post a reversal or compensating entry rather than deleting or overwriting the original history.
Why a labeled field inside one mutable balance is insufficient
A single mutable balance such as balance = 120, even when accompanied by a description or a “promo included” flag, loses important information. It may not reveal how much came from a payment, how much came from a campaign, which portion expires, or what should happen if the customer receives a refund.
Labels can also drift out of sync with the amount they describe. Concurrent updates, retries, support adjustments, and back-office corrections make this especially risky. When the balance itself is the only authoritative record, reconstructing its history often requires piecing together events from unrelated systems.
Separate accounts make the distinction structural. The current balance of each bucket is derived from its journal entries, while the journal preserves how that balance changed. This supports questions such as:
- How much customer-funded value remains?
- Which promotional grant was consumed?
- Did an expired promotion affect funded value?
- Can a refund be traced to the original payment and funded-balance posting?
- Was a retried usage event posted more than once?
Separation does not by itself resolve every accounting, legal, or operational issue, but it provides a stronger basis for investigation and control than a mutable aggregate field.
When an aggregate available balance is useful—and why it must remain derived
Customers and authorization services often need one convenient number representing currently spendable value. That number can be calculated as:
available balance = eligible funded balance + eligible promotional balance
Eligibility matters. Promotional credits may be limited by service, region, customer segment, expiration date, or contract. Some funded amounts may also be temporarily unavailable because of pending payments, disputes, or other business rules.
The aggregate should therefore be treated as a view or cache, not as the only ledger balance. If it is cached for performance, the system should retain a reliable way to rebuild and verify it from the underlying accounts. The authorization decision should also record which bucket or buckets were reserved and ultimately consumed.
Record the provenance and terms of every credit grant
Account separation answers where value is held. Grant-level provenance explains where it came from and what rules apply to it.
Every funded deposit or promotional grant should have its own stable record. A useful schema normally captures enough information to reproduce the balance, evaluate eligibility, process lifecycle events, and reconcile against the originating system.
Required fields for source, type, amount, unit, issue time, and expiration
A credit-grant record should generally include:
- Grant ID: A stable, unique identifier.
- Customer and account ID: The owner and authoritative balance account.
- Credit type: Customer-funded or promotional, with more specific subtypes where useful.
- Source: Payment, campaign, service recovery, contract allowance, manual adjustment, or another defined origin.
- Amount and unit: Currency, tokens, requests, compute units, or another clearly defined service unit.
- Issue time: When the grant became effective.
- Expiration terms: Expiration timestamp or rule, including the applicable time zone.
- Restrictions: Eligible products, models, regions, projects, or usage categories.
- External reference: The related payment, campaign, authorization, support case, or contract reference.
- Status and lifecycle references: Active, reserved, consumed, expired, cancelled, reversed, or otherwise handled through journal events.
If a service supports multiple currencies or usage units, each amount should be unambiguous. Conversions should be represented as explicit transactions with the applicable rate or rule, not as silent changes to the original grant.
Grant records should describe terms without replacing journal entries. The grant establishes provenance and eligibility; the journal records financial or service-value movements.
Link promotional grants to campaigns and funded value to payment transactions
A customer-funded grant should reference the payment transaction that caused it. The payment record, funding journal transaction, and funded balance account should be traceable through stable identifiers. Payment retries and asynchronous notifications require idempotency controls so the same successful payment does not create duplicate value.
A promotional grant should reference the campaign, contract provision, or authorized adjustment that caused its issuance. Campaign metadata might identify the promotion version, eligibility decision, validity period, and authorizing actor or system.
This relationship makes it possible to reconcile two different questions:
- Did every qualifying payment create the correct funded-value posting exactly once?
- Did every authorized promotion create the intended grant, with the correct restrictions and expiration terms?
Those questions should not be collapsed into one generic “credits issued” total because their source records and business meaning differ.
Post funding, promotions, and usage through distinct transaction paths
Funding, promotional issuance, and usage consumption should use distinct transaction types. They may share ledger infrastructure, but each path should preserve its own source, validation rules, permissions, and reconciliation references.
For example:
- Cash funding: Link the payment record to a balanced journal transaction that increases the customer’s funded-value account.
- Promotional issuance: Link an authorized campaign or adjustment to a balanced transaction that increases the promotional account.
- Usage: Link the metered event to a debit from the specific bucket consumed and to the relevant usage clearing or settlement path.
- Correction: Reverse the original journal transaction and, if needed, post a corrected replacement.
Stable transaction IDs should flow across payment, promotion, metering, and ledger systems. Write APIs should accept idempotency keys, and uniqueness rules should reject duplicate posting attempts without treating legitimate follow-on events as duplicates.
Make the depletion policy explicit
When both balances are eligible, the system needs a documented consumption order. Common options include:
- Promotional-first: Use eligible promotional value before funded value.
- Funded-first: Preserve promotional value until funded value is depleted.
- Earliest-expiry-first: Consume the eligible grant that will expire soonest.
- Contract-specific ordering: Apply rules defined for a particular customer, plan, or service.
No ordering rule is universally correct. The chosen policy should match customer-facing terms, product behavior, operational goals, and relevant accounting or legal conclusions.
Every usage debit should record the rule version used and identify the exact account or grant allocation. If one charge spans two buckets, the ledger should create bucket-specific debit lines rather than silently reducing a combined balance.
Compact example: one charge across two balances
Assume an account starts with 80 funded units and 30 promotional units. A 50-unit usage charge is processed under a promotional-first policy.
| Stage | Funded balance | Promotional balance | Total available |
|---|---|---|---|
| Before usage | 80 | 30 | 110 |
| Usage debit | 20 | 30 | 50 |
| After usage | 60 | 0 | 60 |
The usage transaction should contain separate lines for the 30-unit promotional debit and the 20-unit funded debit. The total remains convenient for display, but the bucket-specific entries preserve what was consumed.
This is an operational example, not a universal accounting journal. The appropriate general-ledger mapping and financial-statement treatment require review based on the underlying arrangement.
Handle lifecycle events separately for each balance type
Separation must continue after issuance. A system that distinguishes grants initially but merges them during refunds, expiration, or adjustments can still lose provenance.
Design explicit handling for each event:
- Redemption: Identify the account and, where required, the grant consumed.
- Expiration: Expire only eligible promotional or funded grants under their applicable terms; do not reduce another bucket to compensate.
- Cancellation: Reverse the relevant unconsumed grant through an auditable transaction.
- Refund: Define whether refunded usage restores the original bucket, follows a new allocation rule, or returns cash. Preserve the link to the original payment and usage events.
- Transfer: If transfers are allowed, retain the original type and restrictions unless a documented rule explicitly transforms them.
- Adjustment: Require a reason code, authorized actor, source record, and balanced journal entry.
- Reversal: Reference the original transaction and negate it without rewriting history.
Refund behavior deserves particular attention. If a charge consumed promotional value first and funded value second, restoring the entire amount to funded value would change its economic identity. The refund policy should specify whether restoration mirrors the original allocation and how expired or no-longer-eligible promotional value is handled.
Permissions should also differ by event. Issuing a campaign promotion, correcting a funded deposit, and approving a manual adjustment are separate operational powers. Role-based authorization and approval thresholds can reduce accidental or unauthorized changes while preserving an attributable record of who initiated and approved each event.
Reconcile the ledger across payments, usage, promotions, and accounting systems
A balanced operational journal can still contain a correctly formatted entry tied to the wrong external event. Reconciliation tests the ledger against the systems that originate or consume value.
A practical reconciliation process compares:
- Payment processor settlements and refunds with funded-balance postings.
- Campaign authorization records with promotional grants and cancellations.
- Metered usage events with bucket-specific debits.
- Reservations with finalized, released, or timed-out usage charges.
- Expiration schedules with expiration journal entries.
- Reversals and adjustments with their original transactions and approval records.
- Operational ledger totals with the accounting general ledger where applicable.
Exceptions should be visible by source, transaction type, account, and age. A discrepancy queue is more useful when operators can trace an item through stable IDs rather than searching by amount and timestamp alone.
The operational credit ledger and the accounting general ledger serve related but different purposes. The operational ledger may track service units, grant eligibility, real-time authorization, and detailed consumption. The general ledger supports formal financial reporting. Reconciled postings may flow between them, but the operational schema should not be treated as automatically determining accounting classification.
Implementation and evaluation checklist
When designing or evaluating a prepaid credit ledger, confirm that the system can answer these questions clearly:
- Account separation: Are funded and promotional balances held in different authoritative accounts or subledgers?
- Provenance: Can every grant be traced to a payment, campaign, contract term, or approved adjustment?
- Consumption ordering: Is the depletion rule documented, versioned, and recorded with each usage debit?
- Expiration: Are expiration rules grant-specific, time-zone aware, and isolated from ineligible balances?
- Refund behavior: Does the system preserve or intentionally transform the original bucket allocation under a documented policy?
- Lifecycle coverage: Are issuance, redemption, expiration, cancellation, refund, transfer, adjustment, and reversal represented as explicit events?
- Idempotency: Can duplicate payment notifications, usage events, and retries be detected safely?
- Immutability: Are corrections made through reversals or compensating entries instead of destructive edits?
- Reporting: Can finance, product, and operations teams report funded and promotional activity separately?
- Permissions: Are sensitive issuance and adjustment actions restricted and attributable?
- Auditability: Do journal entries carry stable IDs, timestamps, actor information, reason codes, and external references?
- Reconciliation: Can payment, campaign, usage, expiration, refund, reversal, and accounting records be compared systematically?
- Derived balances: Can any displayed aggregate be rebuilt from the authoritative bucket balances?
Testing should cover more than the happy path. Useful scenarios include duplicate events, partial charges across buckets, concurrent usage, refunds after expiration, campaign cancellation, delayed payment confirmation, failed reservations, and out-of-order event delivery.
Accounting and legal treatment requires separate review
Ledger architecture preserves operational facts; it does not establish a universally correct accounting conclusion. Promotional credits may have different implications depending on why they were issued, whether they are transferable or refundable, what the customer contract promises, and where the service operates.
Exact journal-account mappings and financial-statement treatment should be reviewed by qualified accounting professionals. Revenue recognition, tax, escheatment, stored-value regulation, consumer-protection rules, and other legal questions may also vary by business model, contract, and jurisdiction. Legal counsel should review applicable obligations where necessary.
The system should therefore retain enough source data and history to support those determinations without hard-coding one classification into every operational event.
Applying the pattern to metered AI services
Credit separation can matter in any metered service where customers prepay for usage or receive promotional allowances. For an AI service, the unit could represent currency, tokens, requests, or another defined measure. Usage telemetry can initiate charging, but it should not be treated as a ledger posting until the event has passed the service’s validation, deduplication, pricing, and allocation rules.
Token Forge Cloud provides Managed Model APIs for API-first model access and usage data, with a path into private deployment once workloads become predictable. Token Forge Cloud Private LLM Inference supports private deployment paths where models, prompts, and telemetry remain in the customer’s controlled environment. These capabilities concern model access and LLM serving; organizations implementing prepaid balances should use a separate billing and ledger architecture designed for their commercial and accounting requirements.
Next step
Contact Token Forge Cloud to discuss API access, private deployment, and LLM inference cost control.