Credits Are a Financial System. We Built It For You, Enforced in the Request Path.

Most credit systems work fine until real money and real load run through them. That's the moment you find out a credit balance was never just a number; it is a financial system you haven’t fully built. And a financial system has to hold up on several fronts at once: correct under concurrency, accurate in real time, auditable long after the fact, able to scale without becoming the bottleneck, and decoupled from the subscription lifecycle. The two that break first are usually the two that matter most under AI load: a balance that stays correct when thousands of requests hit the same wallet at once, and one that stays current in real time instead of lagging behind what was actually spent. Plenty of systems get one or two of these. Getting all of them at once, under real load, is the part that's hard to build and easy to underestimate.

Enforcement, Not Just Accounting

Credits aren't just a number you display to a customer after the fact. They're an access-control decision. When a request comes in, an API call, a model invocation, an agent action, Stigg checks the cost of that specific action against the customer's entitlements and current balance and returns an allow-or-deny decision synchronously, in the request path, before the action runs. The Report usage measurements endpoint hands back the updated balance in the same call, so the next decision is made against a live number, not a stale one. What happens at zero is a policy you choose. Stigg lets you set a soft or hard limit on the credit balance. With a hard limit, enforcement is exact: the customer consumes precisely what's in the available balance and can't spill past it, so a 15-credit action against a 12-credit wallet is stopped before it runs rather than corrected after the fact. Getting that right at real-time speed is the hard part, and it's where most homegrown systems give up.

With a soft limit, you allow the balance to go negative and decide how the overage is handled: either the overdraft settles automatically the next time the customer is granted or buys credits, or you attach an overage price (say $0.10 per credit) and bill the excess at the end of the period, which doubles as a natural nudge toward a higher tier. Either way the shortfall stays visible and reconciled, never a silent hole. That's the difference between a credits system that reports what already happened and one that informs what's about to happen. It's also why credits have to live in the request path at all, not in a nightly reconciliation job: the decision is only useful if it arrives before the action runs.

A credit balance is a double-entry ledger, not a counter.

A double-entry system records every movement as two matching entries, a debit against one account and a credit to another, so nothing is ever silently overwritten and every balance can be reconstructed from its history. That gives you a ledger that is append-only, self-balancing (every debit has a matching credit), and fully auditable.

That distinction sounds academic until it isn't. The single biggest regret of engineers who have built credits systems at scale usually isn't a scaling war story. It's an accounting decision: not going double-entry from day one. It's an easy corner to cut. A credit balance looks like a number you decrement, so most systems model it exactly that way: balance minus cost. That works right up until the business asks a question the number can't answer. Where did those credits go, recognized revenue, an expired grant, a refund, a write-off? Which portion of this balance is promotional and should hit zero and stop, versus paid and refundable? How do you write off part of a balance without destroying the record of the rest? A single mutable balance has one slot and no memory, so every one of those events collapses into the same subtraction. Double-entry fixes this by refusing to let value appear or vanish: every credit moves from one account to another, and the balance becomes a projection over an immutable history of those movements rather than the source of truth itself. That single shift is what unlocks the entire credits lifecycle. Grants with expiry, breakage, refunds, partial write-offs, reservations, and clean revenue recognition all become entries you add, never a lossy edit to a counter. The catch most teams miss is that this is a one-way door: deriving a running balance from a ledger is trivial, but you cannot reconstruct a ledger you never wrote. You either start double-entry, or you migrate to it later under production load, with the history you needed already gone.

This is the difference between a credit system that occasionally can't explain itself and one that always can. Without a real ledger underneath, high-concurrency credit usage produces exactly the failures teams dread: balances that silently drift negative, race conditions, audit trails rebuilt from logs after the fact, and no clean way to support priority-based consumption or graceful expiration. With a double-entry ledger, the enforcement decision happens synchronously in the request path, before compute runs, so a wallet that's out of credits triggers whatever policy you set, a hard stop or a tracked overdraft, before the action executes rather than after the invoice arrives. It also makes reserve-and-settle possible for long-running agent calls, where the final cost isn't known until the work completes: you hold credits up front, then settle the exact amount when the action finishes.

Every AI company is, in effect, building a bank. The ones that get it right build the ledger first.

Five Things a Real Credits System Has to Get Right

Correctness. Treat a balance as a single mutable number and it will eventually drift: a write gets lost under load, two updates step on each other, and the figure in your database slowly stops matching what the customer actually used. The fix is to stop storing a number at all. Every grant and every deduction is a discrete, timestamped, immutable entry in a double-entry ledger, not a mutable balance field you can accidentally overwrite. Nothing is silently lost, and nothing is double-counted, because there's no single mutable number to overwrite. Deduplication is built in: every reported usage event and consumption call carries a required idempotency key, so a duplicate or retried request is only counted once. And when a wallet holds several grants, consumption follows a fixed order (priority, then expiration, then category, then effective date, then creation date), with a separate ledger entry recorded for each grant a deduction draws from. The result is behavior that stays predictable and easy to trace as usage scales.

Real-time balance. A balance check that lives in the request path can fail in two directions: it can be stale, or it can be slow. A balance that updates on a five-minute delay is a window a runaway agent spends straight through. A check that adds latency to every call is one your own engineers will eventually route around, which is the failure that shows up first in practice. Stigg gives you two write paths built for exactly that tradeoff. The Report usage measurements endpoint is synchronous: it returns the updated credit balance in the same response, reflecting the deduction immediately at sub-millisecond latency rather than after a delay, so the next decision is always made against a current balance. The read is served from a low-latency write-back cache, while the ledger remains the single source of truth and the cache reconciles to it in the background. That's the path for strict, real-time enforcement like AI token consumption or per-call API charges. The Report usage events endpoint is asynchronous, landing in around ten seconds, and built for high-volume ingestion**, scaling to as much as 1,000,000 events per second on BYOC**. Both settle to the same source-of-truth balance underneath, so the only thing you're choosing is latency versus volume, not accuracy.

Auditability. Credits break revenue recognition in a way finance feels before engineering does. When a subscription resets mid-cycle, finance still has to recognize revenue on what was actually consumed in the period, split across months when a grant spans them, and tie allowance back to real usage at close. If the only record is a mutable balance and a pile of application logs, that reconstruction happens by hand, under deadline. Stigg keeps the trail finance needs as a byproduct of how credits work. Every burn, expiry, and revocation is captured in an append-only ledger, and every grant carries a per-unit cost basis, lifecycle dates, and a category of paid or promotional. That's enough to calculate revenue directly from consumption: deferred revenue is remaining credits times cost basis, recognized revenue is consumed credits times cost basis, and breakage is expired credits times cost basis, with promotional grants carrying zero cost basis and generating no revenue. The credit tables export to your warehouse and join into an ERP like NetSuite or SAP through your existing ETL, so the evidence trail auditors ask for is already there instead of reconstructed after the fact.

All of it supports ASC 606 revenue recognition, which for credit-based models is quietly becoming a SOX-grade audit requirement rather than a finance afterthought.

Scalability. AI-era usage doesn't look like SaaS-era usage. A single agent session can fan out into thousands of billable events in seconds, across sub-agents all drawing from the same pool, and that's exactly the load that takes down a homegrown counter the moment a product catches on. The metering architecture is built for exactly that load. Events can be reported in batches of up to 1,000, in parallel from multiple distributed reporters with no coordination between them, and built-in idempotency means a duplicate is only ever counted once. Current usage is served from a distributed cache replicated across regions, so reads stay fast wherever the traffic is. On Stigg Cloud that scales to 100k events per second per account, and when you need more, the BYOC option runs the metering service in your own cloud and supports 1M+ events per second. Either way, the ledger keeps up instead of becoming the bottleneck. 

Visibility. "Where did my credits go?" is the question that turns into a support ticket, and homegrown systems usually can't answer it past a single balance number. 

Both you and your customers need to see not just what's left, but what each deduction was actually spent on. Every deduction in Stigg is traceable to the specific action that caused it, so a customer can see which request or feature drew down their balance and what remains. And it goes past the feature level: credit usage can be grouped by any dimension attached to your usage events, with feature and user available by default and custom keys like model, region, or workspace ID appearing automatically, searchable when your events carry a lot of metadata. The chart and the ranked breakdown of top sources update instantly as you change the dimension. That's the difference between telling a customer "you used 400 credits" and showing them "User A spent 400 credits on gpt-4o queries," which is the kind of detail that closes a support ticket instead of opening one.

How to Defend This Internally

The pitch to your own team isn't "credits, but nicer." It's that the correctness problems you'd otherwise own, race conditions under concurrency, reconciliation gaps, audit trails built after the fact, are handled at the ledger level, with the enforcement decision available in the request path and failure behavior explicit and in your control rather than implicit and discovered in production. When Stigg itself is unreachable, reads fall back to a local cache and keep serving last-known state, and the fallback behavior for checks is explicit and configurable per feature, flagged so you can alert on it rather than find out during a billing dispute.

You can build all of this yourself. The real question is whether ledger correctness, real-time enforcement, and an auditable revenue trail are where you want your engineers spending the next year, or whether that year is better spent on the product only you can build.

Explore the Credits Engine →