Credit Pricing: Models, Infrastructure, and Pitfalls

The credit system works fine in staging. In production, a customer runs three agent sessions in parallel and the balance depletes three times faster than it should because concurrent writes aren't handled correctly. The overage posts before anyone notices.

Credit pricing is straightforward to design and harder to get right under real workloads. This guide covers the infrastructure required to keep it consistent in production.

What is credit pricing?

Credit pricing is a model where customers purchase a balance of credits upfront and consume that balance as they use the product.

Credits function as a unit of value inside the system. Each action, API call, token consumed, or agent task reduces the customer’s balance based on defined rules.

This differs from pay-as-you-go models, where usage is recorded first and billed later. With credit pricing, the purchase happens before usage, so the system needs to track and enforce a live balance during each request.

Credits also introduce a separation between systems. Billing handles the purchase of credit blocks, while the entitlements layer uses the current balance to decide whether a request can proceed.

These two layers operate on different timelines, but they need to stay consistent so usage, limits, and charges align.

What data model does credit pricing require?

Credit pricing requires a data model that tracks more than a single balance, since enforcement, billing, and audit depend on how credits are issued and consumed over time.

Each credit block issued to a customer carries its own attributes:

• Amount: Number of credits in the block
• Expiry date: Determines when the block becomes invalid and affects burn order
• Cost basis: What the customer paid, used for revenue recognition
• Category: Paid or promotional, which affects accounting treatment
• Depletion behavior: Whether usage stops at zero or continues with overage

As customers purchase credits over time, the system accumulates multiple blocks with different properties. This creates a ledger of credit events rather than a single stored balance.

Each debit references the block it draws from, along with the order of consumption and the timestamp of the event. This keeps usage aligned with expiry rules, cost basis, and accounting requirements.

The system also needs to treat the ledger as append-only. Every credit grant and debit is recorded as an immutable event, and the current balance is derived from those records. This structure keeps usage, billing, and finance data consistent and auditable.

How burn order works in credit pricing

Burn order defines how the system selects which credit block to debit when a customer has multiple active balances. This is a configuration decision that affects both user experience and financial outcomes.

When credits come from different sources, the system needs clear rules for how they are consumed:

• Promotional before paid: Promotional credits usually have no cost basis, so consuming them first preserves the value of paid credits
• Earlier expiry first: Credits that expire sooner are used first to prevent loss from unused balances

Burn order needs to be configurable at the plan and customer level. A single global rule breaks down when promotional grants, trials, and standard purchases exist in the same account.

The table below shows how different scenarios affect the ledger:

Hard vs. soft credit depletion

Hard and soft credit depletion define how the system behaves when a customer’s credit balance reaches zero.

• Hard depletion stops usage at the limit. The system blocks the request, and the application can trigger a paywall, upgrade flow, or top-up action before any additional usage occurs.
• Soft depletion allows usage to continue after the balance is exhausted. The system records this as a negative balance or an overage entry, which is later processed by billing. This keeps workflows running while shifting the system into overage handling.

The choice depends on the plan and use case. A free tier may enforce strict limits, while a paid or enterprise plan may allow continued usage to avoid disruption. The system needs to support these behaviors through configuration so enforcement stays consistent across plans.

The main credit pricing models

Credit pricing models define how credits are issued, consumed, and replenished, and each model requires different enforcement behavior in the system.

As usage patterns become less predictable, hybrid models become the default. A base credit grant covers expected usage, while additional blocks handle spikes.

This introduces more complexity in enforcement. The system needs to manage multiple credit sources at the same time and apply the correct depletion rules without mixing balances or losing track of usage.

What are entitlements in credit pricing?

Entitlements define what a customer is allowed to consume based on their plan and current credit state, and they act as the enforcement layer that applies those limits during a request.

For credit pricing, an entitlement check runs at request time and returns the data needed to decide whether the action can proceed:

• Access status: Whether the request is allowed based on balance and plan
• Usage limit: The credit cap for the current period, if one applies
• Current usage: Derived from metered events attributed to the customer
• Unlimited flag: Indicates plans without a defined cap

Entitlements work differently from role-based access control, which answers whether a user has permission to access a feature. Entitlements evaluate whether an AI agent or user has sufficient balance to make the next request, and what the system should do when that balance runs out mid-session.

Entitlement state comes from multiple sources that need to be resolved at runtime, before the request proceeds. 

The active plan sets the base grant, while parent plans, trials, promotional credits, and add-ons can adjust that value.

That resolution has to happen fast enough that it doesn't add perceptible latency to every API call, which is why it belongs in a dedicated entitlements layer that stays consistent across plans, customers, and requests as pricing evolves.

Credits vs. tokens vs. wallets

Credits, tokens, and wallets represent different layers in the usage and pricing model, from raw consumption to how that consumption is packaged and controlled.

Tokens are the lowest level. They reflect what the model processes and are useful for precise metering, but they expose internal details and can be difficult to use as a pricing unit.

Credits sit above tokens and provide an abstraction layer. A credit can represent a fixed number of tokens or a higher-level action, which allows pricing to stay stable even if the underlying model or cost structure changes.

Wallets group and manage balances. A wallet can hold one or more credit balances and can be assigned at different levels, such as user, agent, team, product, department, or organization. This supports allocation and governance, where a total budget is distributed and tracked across multiple entities.

The abstraction you expose shapes the system design. Token-based models require fine-grained metering at the model level. Credit-based models require a mapping layer between usage and pricing. Wallet-based systems require hierarchical balance tracking with allocation rules across levels.

Where in-house credit pricing systems break

In-house credit pricing systems break when multiple parts of the system try to update and enforce the same balance at the same time.

A simple setup can track usage in isolation. The problems start when usage becomes shared, concurrent, and tied to changing plan state.

As the system scales, the pressure shows up in specific areas:

• Concurrent usage: Multiple users drawing from a shared wallet at the same time can create race conditions, which require atomic debit operations against a ledger to prevent double-spend.
• State consistency: Cached entitlement data becomes outdated when plans change or credits are granted mid-session, which leads to enforcement decisions based on stale state.
• Promotional credit tracking: When paid and promotional credits exist together, the system needs to distinguish them for accounting and reporting purposes.
• Mid-cycle changes: Upgrades introduce new credit grants, updated limits, and changes to burn order that need to take effect immediately.
• Legacy plan support: Customers on older plans still expect their original credit terms, which adds complexity as the product catalog evolves.
• Auditability: Finance requires an append-only ledger so every credit grant and debit can be traced back to a specific event.

At this stage, the system is coordinating state across requests, users, and plans rather than updating a single value.

At enterprise scale, that coordination has to hold across millions of checks per day without becoming a bottleneck, which is where most in-house implementations hit their limit.

Teams often reach this point when internal systems can no longer keep up with pricing and plan changes. What started as a simple credits table becomes a system someone owns full-time.

How to handle credit pricing infrastructure at scale

Handling credit pricing at scale requires separating enforcement, ledger management, and billing so each layer can operate consistently under load.

When those concerns live in the same layer, concurrent sessions produce race conditions, pricing changes require deploys, and the first enterprise audit request exposes gaps in the transaction record.

Stigg is the usage runtime for AI products. Entitlements, credits, usage limits, and spend governance run synchronously in the request path before compute is consumed. For teams hitting the limits of an in-house credit system:

• Sidecar deployment runs alongside your application, caching entitlement state in Redis so checks resolve immediately on cache hits and within 100ms on misses, with a configurable timeout to prevent latency spikes
• BYOC deployment runs inside your own VPC, keeping enforcement operational under high concurrency and upstream interruptions
• Credit ledger tracks credit blocks with expiry, cost basis, and category using append-only events that produce a reconcilable audit trail
• Burn order, depletion behavior, and credit components are configurable per plan without code changes
• Syncs usage events to Stripe or any existing billing provider while keeping enforcement independent of the payment layer

If credit pricing is creating inconsistencies across usage, billing, and enforcement, the issue is architectural.

See how Stigg’s infrastructure handles ledger correctness, burn order, and enforcement at scale.

FAQs

1. How do you prevent double-spending in a credit system?

You prevent double-spending by using atomic operations on an append-only ledger. Each debit is processed as a single transaction, so concurrent requests cannot consume the same credits twice.

2. How do you calculate credit usage in an AI product?

Credit usage is calculated by mapping raw consumption such as tokens or API calls to a defined credit cost. The system applies this mapping at request time so each action deducts from the balance immediately.

3. Can credit pricing work with subscription billing?

Yes, credit pricing can work with subscription billing by issuing credits on a recurring cycle. The subscription defines the grant, while the credit system enforces usage against that balance.

4. Do you need real-time checks for credit enforcement?

Yes, credit enforcement requires real-time checks because the system must verify the balance before each request completes. Delayed checks can allow usage to exceed limits and create inconsistencies.

5. How do you audit credit usage for finance?

Credit usage is audited through an append-only ledger that records every grant and debit event. The balance is derived from these records, which allows finance teams to reconcile usage with revenue.