> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextmoca.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How billing works
> One meter, one number, echoed on every response — what is counted, what is not, and what is never charged.
**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](/limits#per-request-ceilings).
## 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.
```json theme={null}
"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**.
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 sent it. We did not keep it.
`estimate_tokens` is published in full, including a reference implementation
you can run.
`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.
Step by step, with runnable code.