Consume AI usage
Record what a customer consumed and charge it against their balance. Hyperline prices the usage itself and applies the policy markup — an amount sent by the caller is never read. The call writes one append-only ledger entry and updates the customer’s balance atomically. Replaying an idempotency_key returns the original result unchanged.
How it charges depends on the customer’s mode. In wallet mode the usage is priced against the workspace’s resolved rates in the wallet’s minor units, and the wallet ledger is not touched — a background settlement rolls entries up separately. In credits mode it is priced against the policy’s credit rate card and the customer’s credit balance is decremented for real, in the same transaction, with no settlement afterwards; a customer without enough credits is refused with a 402 and nothing is deducted, so a call is never partially charged.
In windows mode the usage is weighted into units and metered against every one of the customer’s overlapping rolling allowances — a 5h and a 7d window, say. Each window instance is anchored at the first call after the previous one expired and runs for exactly its duration, so resets_at is a real instant rather than a moving average. Every window meters every call, and a call that does not fit in all of them is refused whole with a 402 carrying meters and the soonest resets_at: no window is incremented, so a refused call leaves no trace.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Consumption payload.
Customer to bill — the external id your application knows them by, or a Hyperline cus_… id. Resolved exactly the way AI telemetry resolves it.
1 - 255"acme-corp"
What was consumed. Priced server-side against your resolved rates — an amount sent by the client is never trusted, and never read.
Replay key. Replaying it returns the original amount and breakdown unchanged, with a freshly read balance.
1 - 255"cns_9f2c1ab4e77d3105bb0a"
The agent making the call, as run({ agent }) names it. Optional, and absent means the customer's shared pool — which is what every call did before per-agent billing existed. Naming an agent only changes anything once an operator has given that agent a billing policy of its own; until then it resolves to the same shared pool and the response says so with agent: null.
1 - 128"invoice-copilot"
Response
Consumption recorded.
The billing scope that answered: the agent's own slug when it has a policy of its own, and null when the customer's shared pool answered — including when an agent was named but has no policy of its own.
"invoice-copilot"
Total charged, at full precision — a sub-cent model call is not rounded away, and neither is a fractional credit.
"4.182"
What amount and every breakdown line count: the wallet's minor units, credit units, or weighted allowance units.
minor_units, credits, units "minor_units"
Itemized lines behind amount: one per LLM call, one per cost item, plus a markup line when the policy charges one. In credits mode every line is in credits, and a line the rate card did not price directly also carries the usd_amount it was converted from. Read each line's price_status: a line nothing could price is present at 0 and marked unpriced rather than dropped, so the receipt always accounts for everything that was sent.
What the customer can spend. In wallet mode this is the shadow balance — micro-consumption never touches the wallet ledger directly. In credits mode it is the credit pot itself, read live. In windows mode the three numbers describe the binding window, the one with least room left and therefore the one that will refuse the next call; meters carries every window separately.
Every rolling allowance window after this call, in windows mode — the units it just consumed are already in used_units. Null in every other mode.
Whether the customer's kill switch is on. Consumption is still recorded when it is — blocking is a gate for check, not a way to lose ledger entries.
false
Set when part of this consume could not be priced. The customer was still charged for the lines that could be, and the unpriceable ones are in breakdown with price_status: "unpriced". Null otherwise.
True when THIS call was priced as overage: it crossed the scope's boundary and the policy is metered, so the whole call was re-priced in USD and denomination is minor_units rather than credits or units. A replay reports what the original call did.
true