12. Metering and billing
Two different subjects share these words, and mixing them up leads to wrong designs in both directions:
- A vertical billing its customers. A support desk charging for AI answers, or a field-service firm invoicing hours and parts. That is domain logic, so it belongs in engines and verticals.
- The platform billing a tenant for using Substrat. Apps installed, engines licensed, models called, storage held. That is platform logic, so it belongs in the control plane.
They share one principle, and it is the thread through this chapter: count exactly, price separately, and never let a price change a count.
Part one: a vertical meters its own customers
Quantities, not prices
The metering engine records how much. It has no currency, no rate, no plan, and no idea what anything costs. That line is drawn deliberately. One customer rounds differently, another offers a volume discount, a third changes price mid-month. None of those decisions can be wrong for every vertical, so by chapter 7's test none of them belongs in an engine. What would be wrong for every vertical is losing a unit or counting one twice, so that is what the engine owns.
A meter has a key, a unit, and a kind:
- a counter sums what is recorded (tokens used, messages sent);
- a gauge records a level and takes the maximum within a window, carrying the last level forward into windows where nothing was recorded (seats, stored documents).
A meter's kind and unit are frozen once set. A counter that later became a gauge would reinterpret every entry already written.
Recording, and the invariants that make it safe
// inside the vertical's own operation, in the same transaction as the work
recordUsage(ctx, {
meter: 'ai.tokens.output',
qty: String(outputTokens),
subject: { entityType: 'conversation', entityId: conversationId },
dedupeKey: `${turnId}:out`,
});The engine is composed by call (chapter 7), and that choice matters here more than anywhere. The usage entry commits in the same transaction as the work it measures. There is no gap in which an answer was delivered and its tokens were not recorded, or the tokens were recorded for an answer that rolled back.
What the engine refuses:
- A replay with the same dedupe key returns the original entry, marked as deduplicated, and emits nothing. The same key with a different quantity throws. That is not a replay but two different claims about one event, and one of them is wrong.
- An entry dated inside a closed period throws. Once a period is closed, its numbers cannot change underneath an invoice built from them.
- An entry dated more than five minutes in the future throws. The close horizon only moves forward, so an entry dated past a close that has not happened yet could end up counted by no period at all.
- A negative gauge, or an entry against an inactive meter, throws.
Closing a period
closePeriod totals every meter over a window and freezes the result as period lines. Closes are monotonic: a new period may not overlap one already closed. It emits metering.period-closed with the lines in the payload, fat as chapter 5 requires, so a consumer never has to read back. Nothing schedules a close. When a period ends is a business decision (calendar month, contract anniversary, on demand), so it belongs to the vertical.
Where the price comes in
The vertical holds the rate card, in its own table, with its own permission. The support-desk reference vertical stores rates per meter with an effective date, and prices usage for display by joining each entry to the rate in force when it was recorded. A rate change next month does not reprice last month.
Handing it to invoicing
Invoicing is the other half, and it is composed by event. A vertical or engine emits a billable event, and the invoicing engine consumes it into the customer's single open billing basis: the set of lines a real invoice will be issued from. Today it consumes three events: a completed work order, a placed commerce order paid by invoice, and a closed timesheet period.
Each line copies its price from the event payload at write time, so last month's work is never billed at today's price. A basis holds one currency, checked on every write. Once exported it is immutable, which is why invoicing has no in-scope exports (chapter 5): nothing may call in halfway through and change a basis the accounts already hold.
Two gaps are worth stating plainly:
- Metering does not feed invoicing yet. Invoicing does not consume
metering.period-closed. The intended shape is for the vertical to price the closed lines with its own rate card and emit them as a billable event. On the invoicing side that is an additive new consumed event, designed and not built. - Nothing consumes the export event. No accounting connector takes an exported basis today. The one accounting connector that exists reads bookkeeping from the ledger and has no write path.
Part two: the platform meters a tenant
Meter, don't bill
The platform's rule is count everything exactly, store no bill. Usage is recorded as facts. Prices and margins are applied when someone reads, and nothing stores a computed charge. So a pricing change never requires a data migration, and a count is never tangled with a number that was a commercial decision.
The commercial design names four meters. Here is the state of each:
| Meter | Counts | State |
|---|---|---|
| 1. Base fee | active tenants and active scopes | counted, live |
| 2. Engine licensing | entitlements, grouped by key and plan, with expired ones counted apart | counted, live |
| 3. Usage | platform-provided model calls, with tokens and list price | counted, and priced when read |
| event history retained | measurable in the lake, and nothing reads it yet | |
| storage (scope databases) | sampled daily and read on demand, per tenant. Not priced | |
| API calls | not counted | |
| 4. Network transactions | orders flowing between tenants | not countable, because that flow does not exist |
Meters 1 and 2 are folds over the directory, computed on read and never stored. Operators see them, and model usage, in the console's Meters view, with a per-tenant card on each tenant.
Entitlements: the licence, not the enforcement
An entitlement is a row naming a tenant and a key, optionally with a plan, a quota and an expiry. The kernel enforces presence and expiry: a module whose key the tenant does not hold is not registered, so its operations do not resolve (chapter 3). plan and quota are expression only. A module can read them through ctx.entitlement(key) and act on them, but nothing in the platform enforces a quota.
Model usage, end to end
Platform-provided models are the one part of usage that is complete from call to price:
- A vertical calls a model through the model host. That happens around an operation, never inside one, because a model call is a multi-second network round trip (chapter 4).
- The host resolves the provider with platform-held credentials, makes the call, and builds a usage line: token counts, the list price computed on the platform's side from a generated rate card, and five attribution keys (tenant, scope, vertical, version, operation).
- The vertical records that line through its own operation, which raises it as a platform intent, atomically with whatever the answer changed.
- The platform drain checks that the line's tenant, scope and vertical match the scope it was drained from, so a vertical cannot bill a model call to someone else, and writes it to the directory. The write is idempotent on the request id and kept for 400 days.
- When staff read the summary, a margin is applied, 20% unless configured otherwise. Nothing stores the result.
Two numbers exist, and both are correct. The platform's list price plus margin is what the platform charges the tenant. The vertical's own rate card is what the tenant charges its customers. Reconciling them is the tenant's business.
One known hole: a vertical that holds the models binding can call it directly, outside the model host, and that call is not metered.
Storage: the honest answer
Storage is measured, not yet priced. It is the sum of a tenant's scope databases, each one's size as the Durable Object SQL API reports it (page_count × page_size on SQLite). There are two readings of it.
The stored figure is in the console's Meters view and on each tenant's page. It covers every scope that holds data, archived and suspended ones included, since their storage is kept until they are reaped. The scheduled pass samples each scope at most once a day. A serving scope is read only when another part of the same pass already woke it; a scope that is not serving is read anyway, since nothing else wakes it. The pass keeps one sample per scope per day for thirteen months, and a reaped scope's days stay for the same thirteen months, so the month it was reaped in can still be billed. The figure says how many scopes it covers, how old its oldest sample is and how many scopes' last read failed, and it is called a total only when it covers every scope, none is failing and every sample is under two days old.
The live reading is a button on the tenant's page. It wakes every scope it reads, so it waits to be asked.
What both leave out, and say they leave out:
- Attachment files. Attachment rows record their own byte size, but the bytes live in a blob store rather than in the scope. The stored figure keeps what those rows sum to beside it, as its own number per scope per day, never added into it.
- Per-tenant D1 databases. They are separate databases.
- The lake's
bytescolumn (chapter 11), which records every event's serialized size as shipped. Summed per tenant after dedupe, it is exact, but it measures event history volume, not database size. It excludes a scope's current rows, its indexes, its attachments, and every row an update overwrote. It is a defensible basis for billing history retention, and it is not a storage meter.
A reading covers at most one page of the tenant's scopes and says when it is partial: a page still to read, or a scope whose read failed. A sum is only called a total when a single page covered every scope and every one answered. A walk over several pages never is, because the directory can change between pages. The daily samples are what a GB-month figure would be built from, but a storage line on an invoice still needs a decision: how to price days the pass did not sample, or whether event-history bytes are the unit being sold instead.
Requests are not billable either
The router's per-request datapoints (chapter 10) are sampled. They are good enough to draw a chart and not good enough to put on an invoice. And a read emits no event, so the spine cannot count API calls either. That is why "API calls" sits uncounted next to storage.
What a tenant sees
The dashboard has a Billing page, and today it is a placeholder, marked as not yet enabled. No payment provider is integrated, no invoice is generated, and nothing takes payment. The platform counts, and the operator bills from those counts outside the product.
The shape, once more
In both halves the count is exact, deduplicated, and written in the same transaction or intent as the thing it counts. The price is applied later, by whoever owns the commercial decision: the vertical for its customers, the platform for its tenants. What is missing is also the same in both halves: the hand-off from a closed count to a document someone pays.
Next: Operating it →