New guide

Refine your pricing strategy with a complete guide to pricing economics for AI agents.

Get the guide
×

Building AI billing infrastructure: an implementation guide for engineering teams

What engineering teams need to settle before building AI billing in-house: business requirements, the data model, pricing math, a reference architecture on AWS, and the patterns that keep every number correct.

Building AI billing infrastructure: an implementation guide for engineering teams

AI billing looks like a counting problem. Record the tokens, multiply by a price, send the total to the billing platform. In practice it is a distributed systems problem with money attached: millions of usage events, variable provider costs underneath every one of them, and customers who expect to pay in very different ways.

This guide is for engineering teams who plan to build billing infrastructure in-house, converting token consumption and task execution into customer-facing billable metrics, with a margin on top that keeps every customer profitable. It is meant to be read before the first table is created.

It covers, in order:

  1. The business requirements that product and revenue teams almost always bring, with worked examples.
  2. The data model and pricing math that satisfy them.
  3. The engineering challenges that make this harder than it looks.
  4. Why a simple in-app implementation fails, and what to build instead.
  5. A reference architecture, the technology choices behind it, and the implementation patterns that keep it correct.

Whatever the final design, the system has to hold three guarantees at all times:

  • Every usage event is billed exactly once. Never lost, never double-counted.
  • Every billable unit carries a known cost and a known margin. Price is derived from cost, not guessed.
  • Every number is explainable. Any invoice line, wallet balance or margin figure can be traced back to the events that produced it.

Part 1: What the business needs

Before any architecture, agree on requirements with product and revenue teams. The eight below come up in almost every AI company. Treat them as the minimum scope, not a wishlist.

1. Calculate billable metrics: credits, currency and outcomes

Raw usage (tokens, model calls, tool calls, minutes of audio) must be converted into the unit the customer actually buys. Three types cover most products:

  • Credits. An abstract unit with a fixed price, for example 1 credit = $0.01. Good for hiding volatile provider costs behind a stable number.
  • Direct currency. Usage is priced straight in USD or INR. Transparent, but every provider price change shows up on the customer's bill.
  • Outcomes. A charge only when a result is achieved, for example $0.90 per resolved support ticket, regardless of how many model calls it took.

2. Manage a wallet per customer, per metric

Each customer needs a balance for each type of unit they hold: a credit wallet, a currency wallet, or an outcome wallet such as "500 prepaid ticket resolutions." The system must always know the current balance, and why it is what it is.

3. Prepaid wallets, charged by usage

The customer tops up first, then usage draws the wallet down. Example: a customer buys $500 of credits; every agent run debits the wallet; at zero, the policy decides what happens next: block new runs, allow a small overdraft, or fall back to pay-as-you-go.

4. Adjust wallets dynamically

Balances do not only change through usage. Revenue and support teams need to apply top-ups, promotional grants, refunds, goodwill credits, corrections and expiries, each one recorded with a reason and an author.

5. Show usage logs to customers

Customers expect to see what they were charged for, run by run:

TimeAgentRunChargedBalance after
10:42:07Support agentrun_8f2112 credits4,988 credits
10:42:19Support agentrun_8f221 resolution499 resolutions
10:43:02Doc parserrun_8f23$0.18$412.40

The customer view shows billable units only. Internal cost and margin must never leak into it.

6. Spend insights for every AI run

Internally, every run needs a cost breakdown: which models were called, how many input and output tokens, which tools ran, and what each cost at the provider's rate at that moment. Example: run_8f21 made 3 model calls, used 6,200 input tokens and 900 output tokens, and cost $0.0321.

7. Margin for every run

With both sides known, margin follows: price charged minus cost incurred. Run_8f21 was charged 12 credits ($0.12) and cost $0.0321, a margin of $0.0879, or about 73%.

8. Customer-level revenue, cost and profit

Roll the runs up per customer, per period: revenue, provider cost, gross profit and margin percentage, sliceable by agent, model and plan. This is the view that tells the revenue team which customers are profitable and which are not.

Part 2: What the business will ask for next

The next five are often labelled nice-to-have. In practice they arrive within the first few enterprise deals, so the data model should support them from day one even if the UI comes later.

1. Per-customer token-to-credit conversion

The default rate might be 1 credit per 1,000 tokens on a given model. An enterprise customer negotiates 1 credit per 1,500 tokens on the same model. Conversion rates therefore cannot be constants in code. They must be data, scoped by customer and model, and versioned by date.

2. Customer-level margin

The default target might be a 60% gross margin, while a strategic account is allowed 40%. Be precise about the formula, because margin and markup are often confused:

  • Margin-based price: price = cost ÷ (1 − margin). A $0.0321 cost at 60% margin is priced at $0.0803.
  • Markup-based price: price = cost × (1 + markup). The same cost with a 60% markup is $0.0514, which is only a 37.5% margin.

Pick one definition, name it explicitly in the schema, and use it everywhere.

3. Composite billable units

One unit the customer buys may be made of many events. A "processed document" priced at $2 might include an OCR call, a classification call, two extraction calls and a validation call. The system must group those events by a shared run or task ID, cost them individually, and bill them as one unit.

4. Hybrid payment

Part prepaid, part pay-as-you-go. Example: a $500 monthly platform fee, plus a $1,000 prepaid wallet, plus postpaid overage at 1.2× the wallet rate once the wallet is empty, invoiced at month end. The rating logic has to know, event by event, which source pays for it.

5. Multiple credit and outcome types

A customer may hold standard credits for fast models, premium credits for reasoning models, and promotional credits that expire in 30 days. The system needs a drawdown order, such as expiring promotional credits first, then the plan's included credits, then purchased credits, and it must apply that order consistently.

Part 3: The data model

All thirteen requirements can be met with five core entities. Getting these right early saves months of migrations later.

EntityWhat it holdsMutabilityTypical store
Usage eventOne raw signal from the product: a model call, tool call or task completionImmutableStream, then ClickHouse
Cost catalogProvider rates per model and unit, with effective datesVersionedRelational DB, cached in Redis
Rate cardBillable metric definitions, conversion rates, margin targets, per-customer overridesVersionedRelational DB, cached in Redis
Wallet ledgerEvery credit and debit to every wallet, with reason and sourceAppend-onlyRelational DB, hot balance in Redis
Rated recordOne billable unit: quantity, price, cost, margin, which wallet paidImmutable once finalClickHouse

The usage event

The product emits one event per billable action. Everything downstream depends on its shape, so define it carefully:

{
  "event_id": "evt_01HZX9K2P7",
  "idempotency_key": "run_8f21:call_2",
  "org_id": "org_acme",
  "customer_id": "cus_4471",
  "run_id": "run_8f21",
  "agent": "support-agent",
  "type": "llm_call",
  "provider": "provider_a",
  "model": "model-large",
  "input_tokens": 2100,
  "output_tokens": 300,
  "outcome": null,
  "occurred_at": "2026-10-15T10:42:06.913Z"
}

Three fields carry most of the weight. The idempotency_key is generated by the producer and is stable across retries, so the same call can never be billed twice. The run_id groups events into a composite unit. The occurred_at timestamp, not the arrival time, decides which price version applies.

Design rules that save pain later

  • Never store money as floats. Use integers in a small unit (for example micro-dollars, where $1 = 1,000,000) or fixed-precision decimals. Per-token costs are tiny, and float rounding across millions of events becomes real money.
  • Version everything that affects price. Cost catalog and rate card rows carry effective_from and effective_to. Every rated record stores the versions it used, so last month's invoice can be recomputed exactly.
  • Make the ledger append-only. A balance is the sum of its entries. Corrections are new entries, never updates. This gives a full audit trail for every wallet for free.
  • Separate customer-facing units from internal cost. Store both on the rated record, but expose only billable units through customer APIs.

Part 4: A worked example, from tokens to margin

Follow one run, run_8f21, through the pricing math. The rates below are illustrative; substitute real provider prices from the cost catalog.

Inputs

  • Cost catalog: model-large costs $3.00 per million input tokens and $15.00 per million output tokens.
  • Rate card (default): 1 credit per 1,000 input tokens and 1 credit per 160 output tokens on model-large. 1 credit sells for $0.01. Minimum margin: 60%.
  • Customer cus_4471 holds a prepaid wallet of 5,000 credits.

Step 1: cost each event. The support agent made three model calls in this run:

EventInput tokensOutput tokensInput costOutput costEvent cost
call_11,800200$0.0054$0.0030$0.0084
call_22,100300$0.0063$0.0045$0.0108
call_32,300400$0.0069$0.0060$0.0129
Run total6,200900$0.0186$0.0135$0.0321

Step 2: convert usage to billable units. Apply the rate card to the run total, not to each call: 6,200 ÷ 1,000 = 6.2 credits for input, plus 900 ÷ 160 = 5.625 credits for output, giving 11.825 credits. Rounded up to the nearest whole credit, the run costs the customer 12 credits ($0.12).

Round once per billable unit. Rounding each of the three calls separately would charge 13 credits, and that systematic over-rounding is exactly the kind of error that leads to customer disputes.

Step 3: check the margin. Revenue $0.12, cost $0.0321, margin $0.0879, or about 73%. That is above the 60% floor, so the record is final.

Step 4: debit the wallet. The ledger gets one entry: usage_debit, 12 credits, reference run_8f21. Balance goes from 5,000 to 4,988 credits.

Step 5: write the rated record. One row in ClickHouse with customer, run, 12 credits, $0.12 revenue, $0.0321 cost, $0.0879 margin, the wallet that paid, and the cost catalog and rate card versions used.

The same run for an enterprise customer

Suppose another customer has negotiated 1 credit per 1,500 input tokens. Input becomes 4.13 credits, output stays 5.625, the total of 9.76 rounds to 10 credits ($0.10). Cost is unchanged at $0.0321, so margin drops to about 68%. Still above the floor.

Why the margin floor matters

Now suppose the provider raises output pricing, or the agent starts producing longer answers. The same rate card can quietly fall below the floor. The rating step should check every unit against the customer's minimum margin and do one of three things, according to policy: alert the revenue team, apply a pre-agreed price adjustment, or flag the record for review. This is how "added margin always gives profitability" becomes a property of the system rather than a hope.

Part 5: The engineering challenges

The pricing math above is the easy part. Four properties of AI usage make the implementation hard.

1. No usage signal can be missed

Every event that is lost is revenue that was paid to a provider and never collected. Events get lost in ordinary ways: an application error after the model call returns, a database timeout, a pod restarted mid-request, a network blip on the way to the billing service. The capture path must survive all of them, and the opposite failure too, because a retried event billed twice is a customer dispute.

2. Billing cannot run in the request thread

If the agent's request handler also computes cost, applies the rate card, debits the wallet and writes analytics, then every billing slowdown becomes a product slowdown, and every billing failure becomes a failed customer request. The request path should do the minimum: a fast balance check, then publish the event. Everything else fans out asynchronously.

3. Event volume is very high

One user action can trigger an agent loop with many model and tool calls, each one a billable event. Across all customers, that quickly reaches millions of events per day, with spikes when one enterprise customer runs a batch job. The pipeline must absorb bursts without dropping events or slowing the product down.

4. Analytics must be computed as events are processed

Revenue teams want margin per customer, per agent and per model, close to real time. Running GROUP BY over hundreds of millions of raw rows every time a dashboard loads is slow and expensive. Aggregates need to be maintained incrementally, as each batch of rated events lands, so dashboards read small, pre-computed tables.

Part 6: Why simple application logic fails

The tempting first design keeps everything inside the application:

  1. The request handler writes each usage event as a row in the application database.
  2. A background job reads unprocessed rows into memory, applies pricing, and updates balances.
  3. The job writes results into another table, or another database, for analytics.

It works in a demo and for the first handful of customers. Under real conditions it breaks in three predictable ways.

Missed events put revenue at risk. The write in step 1 shares fate with the request. If the handler crashes, times out or rolls back after the model call has already been paid for, the event is gone. Nothing alerts on a row that was never written, so the loss is silent.

Retries and failover have to be built by hand. The background job needs to know which rows it has processed, resume from the right place after a crash, avoid processing the same row twice when two instances run, and route poison records somewhere safe. That is a message queue with offsets and dead-letter handling, rebuilt badly inside a database table.

Every application deploy is a billing outage. Because capture and processing live in the application server, every release, scale-down or restart interrupts them. In-memory work is lost, half-processed batches are left behind, and the billing pipeline inherits the deploy cadence of the product, which in an AI company can be several times a day.

The verdict: billing for AI usage cannot be an application feature. It has to be its own service, with its own durability, scaling and deployment lifecycle.

Part 7: The solution, a dedicated billing microservice

Move capture, rating, wallets and analytics into a service that runs outside the application servers. It has three jobs.

Stay up when the product does not. The service runs on its own containers, scales on its own metrics, and deploys on its own schedule. A product release never pauses billing, and a billing release never touches the product.

Retry and fail over automatically. Events land in a durable stream before anything else happens to them. If a worker crashes, another picks up from the last checkpoint. If a downstream store is unavailable, events wait in the stream instead of disappearing. Records that fail repeatedly go to a dead-letter queue for inspection, without blocking everything behind them.

Integrate through a small, stable API. The product should only need a handful of endpoints:

EndpointPurposeCalled by
POST /v1/signalIngest one usage event. Idempotent on idempotency_key; returns 202 Accepted once the event is durably queuedProduct, after each model or tool call
POST /v1/signal/batchIngest many events in one requestProduct, for high-volume agents
POST /v1/authorizeCheck, and optionally reserve, balance before an expensive runProduct, before starting a run
GET /v1/wallets/{customer_id}Current balances per wallet typeProduct UI, customer portal
GET /v1/usage/{customer_id}Customer-facing usage log, billable units onlyCustomer portal
POST /v1/wallets/{id}/adjustmentsTop-ups, grants, refunds, corrections, with reasonRevenue and support tools

One detail is easy to miss: durability starts in the product, not in the billing service. The client library that calls /v1/signal should buffer events locally and retry with the same idempotency key whenever the API is unreachable. Otherwise a short billing outage still loses events on the product side.

Part 8: Technology choices

Six layers make up the service. The reference architecture in the next section uses AWS and the specific tools named below, but each layer has credible alternatives.

LayerJobReference choiceAlternatives
Edge computeAccept signals, validate, check balance, publishAuto-scaling containers (ECS on EC2) behind a load balancerKubernetes, Fargate, Cloud Run
Event streamingDurable, replayable buffer between every stageAmazon Kinesis Data StreamsKafka, Redpanda, Google Pub/Sub
Fast-write storeAbsorb millions of rated events in large batchesClickHouseApache Druid, Apache Pinot
AnalyticsPre-aggregated revenue, cost and margin viewsClickHouse materialized viewsA separate warehouse fed from ClickHouse
CacheHot wallet balances, rate cards, auth, countersRedis (Upstash)ElastiCache, Valkey, DragonflyDB
Relational storeDurable record of customers, plans, rate cards, ledgerSupabase (Postgres)Any managed Postgres or MySQL

A few notes on why these fit.

Edge compute must scale horizontally. The ingestion tier does little work per request but sees the full burst of traffic. Stateless containers that scale on request count or CPU are the simplest way to keep it responsive.

Size the stream for peak, not average. In Kinesis, each shard accepts writes of up to 1 MB or 1,000 records per second and serves reads of up to 2 MB per second. Pick a partition key with enough spread, such as customer_id combined with run_id, so one busy customer does not saturate a single shard.

ClickHouse wants large batches. It is built for bulk inserts, and ClickHouse's own guidance favours batches in the thousands of rows over a stream of single-row writes. Synchronous batch inserts also get automatic insert deduplication, which makes retried batches safe. This is why a dedicated consumer, rather than every worker, should write to it.

Redis is the hot path, not the source of truth. It answers "does this customer have balance?" in a millisecond, and Lua scripts let a balance check and debit run as one atomic step. But a cache can be evicted or fail, so every balance change must also be written to the relational ledger.

The relational store holds what must never be lost. Customers, plans, rate card versions, wallet ledger entries and adjustments belong in a transactional database with backups and point-in-time recovery.

Part 9: Reference architecture

The proposal below puts the six layers together into one pipeline. A signal moves in a single direction, through two streams, and is never held only in memory.

Follow a single signal through it:

  1. Capture. After each model or tool call, the product sends an event to api/v1/signal. A load balancer spreads requests across the ingestion tasks.
  2. Validate and admit. The ingestion service (ECS on EC2, three tasks) validates the payload and API key against Redis, checks the customer's balance, rejects duplicate idempotency keys, and publishes the event to the Kinesis ingestion stream. It responds 202 Accepted as soon as the stream has the event. Nothing slow sits on the request path.
  3. Rate. Worker nodes (ECS on EC2, three tasks with several internal workers each) pull from the ingestion stream on a short interval, every 15 seconds in this design. For each event, they load the org- and customer-scoped rate card and cost catalog from Redis, compute cost, billable units and margin, debit the wallet atomically, and update consumed counters.
  4. Forward, then checkpoint. Workers publish rated records to a second stream, the ClickHouse stream. Only after that write succeeds do they commit their offset on the ingestion stream.
  5. Persist state. Balance and counter changes are written through to Supabase as ledger entries, so Redis can always be rebuilt from the system of record.
  6. Store. A consumer on EC2 reads the ClickHouse stream, removes any duplicates, and inserts rated records in large batches. Each record carries a pending or success status, and materialized views update the margin rollups on every insert.
  7. Archive. Older ClickHouse partitions move to S3 for long-term retention and replay.

Why two streams instead of one? The second stream decouples rating from storage. If ClickHouse is slow or down for maintenance, rated records queue safely in the stream, workers keep rating, and the consumer catches up when the store returns. It also lets the consumer batch writes the way ClickHouse prefers, independently of how fast workers produce them.

The deploy rule from the original design is worth repeating: when a worker node is updated, it stops pulling from Kinesis, finishes every in-flight task in its pipeline, checkpoints, and only then shuts down. The new version starts pulling only once it is healthy.

Part 10: Implementation patterns that keep it correct

The architecture gives the system its shape. These patterns are what make it trustworthy.

Idempotency at every hop

Streams deliver at least once. The Kinesis Client Library stores checkpoints in a DynamoDB lease table, and after a worker failure another worker resumes from the last checkpoint, which means some records are processed twice. Plan for duplicates everywhere:

  • Producer: generate the idempotency_key once and reuse it on every retry.
  • Ingestion: reject a key already seen in a short window, using a Redis SET key NX EX check.
  • Wallet debit: make the debit itself idempotent on the key (see the script below).
  • Storage: use a ReplacingMergeTree table keyed on event_id in ClickHouse, and query with FINAL or argMax for billing-grade totals, because duplicates collapse only when background merges run.

Checkpoint only after forwarding

A worker commits its position on the ingestion stream only after the rated record has been accepted by the next stream. If it crashes between the two, the record is replayed and deduplicated downstream. Committing first and forwarding second is the one ordering that loses money.

Atomic wallet debits

A balance check followed by a separate decrement is a race condition: two concurrent runs can both see enough balance and both spend it. Do the check and the debit in one atomic Lua script:

-- KEYS[1] = wallet balance key, KEYS[2] = idempotency key
-- ARGV[1] = amount (integer units), ARGV[2] = overdraft limit, ARGV[3] = dedupe TTL (s)
if not redis.call('SET', KEYS[2], 1, 'NX', 'EX', ARGV[3]) then
  return {'duplicate', tonumber(redis.call('GET', KEYS[1]) or '0')}
end
local balance = tonumber(redis.call('GET', KEYS[1]) or '0')
local amount = tonumber(ARGV[1])
if balance - amount < -tonumber(ARGV[2]) then
  redis.call('DEL', KEYS[2])
  return {'insufficient', balance}
end
return {'ok', redis.call('DECRBY', KEYS[1], amount)}

Every successful debit must also produce a ledger entry in the relational store. Write it through an outbox or a dedicated stream rather than inline, so a slow database never blocks rating. If Redis is ever lost, balances are rebuilt from the ledger.

Reserve, then settle, for expensive runs

For long agent runs, /v1/authorize can place a hold for an estimated amount before the run starts. When the run finishes, the actual cost is settled and the unused part of the hold is released. Holds carry a TTL so an abandoned run never locks a balance forever.

Price by event time, not arrival time

Events arrive late and out of order. Always look up the cost catalog and rate card version in effect at occurred_at. Define a cutoff for each billing period; events that arrive after an invoice is closed become adjustments on the next one, never silent edits to the past.

Graceful deploys

On ECS, a stopping task receives SIGTERM and, by default, 30 seconds later a SIGKILL; the window is configurable through stopTimeout. Workers should handle SIGTERM by stopping new reads from the stream, finishing in-flight records, checkpointing, then exiting. Set the timeout longer than the slowest batch. For the ingestion tier, the load balancer deregisters the task first so no new requests arrive mid-shutdown.

Dead letters and replay

A record that fails rating repeatedly, because of a missing rate card or a malformed payload, goes to a dead-letter queue with the error attached. Fix the cause, then replay. Never let one bad record block a shard.

Reconcile daily

Automate three checks: event counts in the stream against rows in ClickHouse; the sum of each wallet's ledger against its Redis balance; and computed provider cost against the provider's actual invoice. Any drift is a bug, found in a day instead of at quarter close.

Monitor what matters

Alert on stream consumer lag (iterator age), dead-letter queue depth, ingestion error rate, ledger and cache drift, and the count of rated records below the margin floor.

Part 11: Analytics, computed as events land

Requirements 6 to 8, spend per run, margin per run and customer-level profitability, all come from the rated records table. The trick is to keep dashboard queries off the raw rows.

The rated records table

Every billable unit lands here, with both revenue and cost stored as integer micro-dollars:

CREATE TABLE rated_records
(
    event_id         String,
    run_id           String,
    org_id           LowCardinality(String),
    customer_id      String,
    agent            LowCardinality(String),
    model            LowCardinality(String),
    billable_metric  LowCardinality(String),
    quantity         Decimal(18, 6),
    revenue_micros   Int64,
    cost_micros      Int64,
    status           Enum8('pending' = 1, 'success' = 2),
    rate_card_ver    UInt32,
    cost_catalog_ver UInt32,
    occurred_at      DateTime64(3),
    version          UInt64
)
ENGINE = ReplacingMergeTree(version)
PARTITION BY toYYYYMM(occurred_at)
ORDER BY (customer_id, occurred_at, event_id);

Per-run spend and margin (requirements 6 and 7) are cheap queries on this table, filtered by customer_id and run_id.

Incremental customer rollups

In ClickHouse, a materialized view runs on every inserted block and writes its result into a target table, so aggregates stay current without rescanning history:

CREATE TABLE customer_daily_margin
(
    day             Date,
    customer_id     String,
    agent           LowCardinality(String),
    model           LowCardinality(String),
    runs            AggregateFunction(uniq, String),
    revenue_micros  SimpleAggregateFunction(sum, Int64),
    cost_micros     SimpleAggregateFunction(sum, Int64)
)
ENGINE = AggregatingMergeTree
ORDER BY (customer_id, day, agent, model);

CREATE MATERIALIZED VIEW customer_daily_margin_mv TO customer_daily_margin AS
SELECT
    toDate(occurred_at)  AS day,
    customer_id, agent, model,
    uniqState(run_id)    AS runs,
    sum(revenue_micros)  AS revenue_micros,
    sum(cost_micros)     AS cost_micros
FROM rated_records
WHERE status = 'success'
GROUP BY day, customer_id, agent, model;

The customer profitability view for the revenue team (requirement 8) then reads a small table:

SELECT
    customer_id,
    sum(revenue_micros) / 1e6                       AS revenue,
    sum(cost_micros) / 1e6                          AS cost,
    (sum(revenue_micros) - sum(cost_micros)) / 1e6  AS gross_profit,
    round(100 * (1 - sum(cost_micros) / nullIf(sum(revenue_micros), 0)), 1) AS margin_pct
FROM customer_daily_margin
WHERE day >= toStartOfMonth(today())
GROUP BY customer_id
ORDER BY margin_pct ASC;

The duplicate trap

A materialized view sees every inserted row, including duplicates that ReplacingMergeTree will only collapse later during merges. If a duplicate reaches the raw table, the rollup counts it twice, permanently. That is why deduplication has to happen before the insert, in the consumer, and why the daily reconciliation should compare rollup totals against a FINAL query on the raw table.

Archive the raw history

Raw rated records grow without bound. Keep recent months in ClickHouse for disputes and recomputation, and move older partitions to S3, where they stay available for audit and replay at a fraction of the cost.

Before writing the first line of code

Use this list to check that the design is complete. Every unchecked item is a future incident.

  • The usage event schema is agreed with product, including idempotency_key, run_id and occurred_at.
  • Money is stored as integers or fixed-precision decimals everywhere.
  • Cost catalog and rate cards are versioned data, not constants in code.
  • Margin is defined once (margin or markup) and a minimum margin is enforced per customer.
  • The product client buffers and retries events with stable idempotency keys.
  • Ingestion only validates, checks balance and publishes; rating happens asynchronously.
  • Stream capacity is sized for peak traffic, with a partition key that spreads hot customers.
  • Workers checkpoint only after forwarding, and deduplicate before writing.
  • Wallet debits are atomic and every debit produces an append-only ledger entry.
  • Balances can be rebuilt from the ledger if the cache is lost.
  • Late events, dead letters and replays have a defined path.
  • Workers and ingestion tasks shut down gracefully on deploy.
  • Reconciliation runs daily across stream, store, ledger and provider invoices.
  • Dashboards read pre-aggregated tables, never raw events.
  • Someone owns this system, and its on-call rotation, permanently.

The last item is the one most teams underestimate. Everything in this guide can be built, and many teams have built it. But it is a revenue-critical distributed system that must keep changing as pricing changes, and it needs a dedicated team to run it.

If the goal is to understand the problem before building, this guide should cover it. If the goal is to get the outcome without owning the system, that is exactly what we built Clocknext to provide. Either way, the questions in this guide are the right ones to answer first.

Billing engineering, Build vs buy, Infrastructure

Vijayanand Kailash

Vijayanand Kailash

Co-founder & CEO, Clocknext

16 years in tech and counting. In-house billing expert and jack-of-all-trades across product and GTM.