How billing works

Metering is not live yet. The usage receipt described here is designed and sequenced; it does not appear on responses today, and no charges are being raised. This page is published ahead of it so the rules are settled and checkable before the first invoice, not after.What is live today is the quantity itself: the same number the meter will report is already computed on every request and used to enforce your per-request ceiling.

One number, computed once

Every response will carry a usage block. It is the same number the telemetry event records and the same number the invoice line sums — there is no second computation anywhere for it to drift from.

"usage": {
  "meter_version": "npm-2026-08-r1",
  "outcome": "engaged",
  "input_tokens": 14200,
  "charge_multiplier": "1.0",
  "price_version": "npp-2026-08-r1",
  "currency": "USD"
}

Field	What it is
`input_tokens`	What was measured. The metered input for this request. Always emitted, never zeroed — including on requests that carry no charge.
`outcome`	What the engine did. An open enum: `engaged`, `stood_down`, `fallback`, `engine_error`, `empty_input`.
`charge_multiplier`	What it cost, relative to an engaged request. `"0"` means not charged.
`meter_version`	Pins the definition of a billable unit, including the counting rules. Immutable.
`price_version`	Pins the rate card that applied. Separate from `meter_version`.

The measurement and the price are separate fields on purpose. A single field cannot be both “the input you submitted” and “zero when nothing is charged” — on a 100,000-token stand-down those are different numbers. Splitting them means the measurement is always verifiable and the price is always attributable.

Three versions that move independently

policy_version says what ran. meter_version says what a token means. price_version says what it costs. They are deliberately decoupled: a retune must not reprice anyone, and a repricing must not change anyone’s selection. If they were one field, every price change would look like a behaviour change and every retune would look like a price change.

What is metered

Every customer-supplied text field the engine processes:

input_tokens = Σ estimate_tokens(record.text)
             + Σ estimate_tokens(record.title)
             +   estimate_tokens(task.prompt)
             + Σ estimate_tokens(task.recent_prompts)

That is the whole definition. It is computed at the boundary, from your request body, before the engine runs.

Recompute it yourself

The reference implementation, in Python and TypeScript, with a worked example.

What is not metered

Not metered	Why
`keywords`, `tags`, `attributes`	Structurally small. Metering them would complicate a number you have to be able to reproduce, for no extra protection. They are bounded by the published size cap instead.
Anything in the response	You are charged on what you sent, not on what you got back.
`tokens_before` / `tokens_after`	These are the engine’s accounting and are not the meter. See below.

tokens_before is not your bill. On this deployment it happens to work out to Σ estimate_tokens(record.text) — so it is close enough to look like the meter, which is exactly why it is worth being explicit.It is not. The meter also counts record.title, task.prompt and task.recent_prompts, so input_tokens is the larger number. And tokens_before is an engine-internal budgeting quantity by definition: it is a per-record sum taking a maximum against the summary the engine holds, so it is free to move when engine internals move, while the meter is not.Budget against tokens_before. Reconcile an invoice against input_tokens.

Why input, and not tokens saved

Charging for tokens saved is the intuitive model and it is the wrong one, for two reasons we would rather state than have you infer.

It pays us more the more we cut. That is a direct incentive against answer quality — the vendor’s interest and yours point in opposite directions on every request.
It is unstable. A retune would change your bill for identical inputs, making your invoice a function of our tuning decisions rather than of your usage.

Charging on submitted input has its own incentive, and it is worth naming: we are paid more when you send more. The difference is that you observe and control that directly — and our own shadow report is an argument for sending less.

The charge

charge = max( minimum_request_fee,  rate_per_million × charge_multiplier × input_tokens )

charge_multiplier is carried on the receipt for exactly this reason: you never have to look up which multiplier applied to a given request.

Outcome	Charged
`engaged`	The full rate. This is the `1.0` reference.
`fallback` (a selection was returned within budget)	The full rate — you got a usable answer under your budget.
`stood_down`	At the multiplier carried on that request’s receipt, which is not the engaged multiplier.
`engine_error`	Nothing, and the minimum fee does not apply. We never bill for our own failure.
`empty_input` (zero records)	Nothing, and the minimum fee does not apply.
Malformed request (`4xx`)	Nothing. No work happened past parsing.

Rates are not published yet. The rate card, the minimum request fee and the stand-down multiplier are commercial decisions that are not settled. What this page fixes is the structure — the unit, the formula and where each number comes from — so that when the numbers land there is nothing left to argue about except the numbers.

Cases people ask about

Case	Charged
You retry after a failure	As a new request. The work was done twice.
We deliver the same meter event twice internally	Once. Duplicates are deduplicated before the ledger.
Shadow mode	Exactly what the same request would have cost live. Shadow does the full computation, and pricing it identically is what makes its savings projection comparable to the invoice it predicts rather than an optimistic estimate.
A `413` over your ceiling	Nothing. The ceiling is checked before the engine runs.
A `429`	Nothing.

Rounding happens once

Amounts are rounded once, at invoice aggregation, over the summed exact amount — never per request. Per-request rounding of sub-cent amounts is how a million small requests silently become a different invoice from the sum of their receipts.

Disputing a charge

We cannot show you your records, because we never had them. What we can show you is better:

You hold the payload

You sent it. We did not keep it.

We publish the function

estimate_tokens is published in full, including a reference implementation you can run.

The receipt names the version

meter_version pins which definition applied to that request.

So you can recompute the charge yourself, exactly, without taking our word for anything. That is a stronger audit story than “trust our logs”, and it exists because the meter is a pure function of your request body rather than in spite of it.

How to recompute your own bill

Step by step, with runnable code.

Get started

How selection works

Running it in production

Billing

Integrations

One number, computed once

Three versions that move independently

What is metered

Recompute it yourself

What is not metered

Why input, and not tokens saved

The charge

Cases people ask about

Rounding happens once

Disputing a charge

How to recompute your own bill

​One number, computed once

​Three versions that move independently

​What is metered

Recompute it yourself

​What is not metered

​Why input, and not tokens saved

​The charge

​Cases people ask about

​Rounding happens once

​Disputing a charge

How to recompute your own bill

One number, computed once

Three versions that move independently

What is metered

What is not metered

Why input, and not tokens saved

The charge

Cases people ask about

Rounding happens once

Disputing a charge