How the routed-spend band works

This page explains the included routed-spend band on the Billing page, served by GET /platform/v1/billing/band.

What it is

Each paid plan includes a monthly amount of routed provider spend: Developer $2,500/mo, Team $7,500/mo, Growth $25,000/mo, Scale $75,000/mo. Spend past the included amount is counted in whole steps of $5,000, each priced at a flat $60. The step price is a fixed integer dollar amount, never a percentage of spend or savings. Today the band is a visibility number, and the step figure is a display artifact: no published plan charges it, crossing emits no charge, and no traffic is touched. overageBilled is always false.

How it is computed

All money is integer micro-USD, one millionth of a dollar. Whole-dollar catalog values convert by multiplying by 1,000,000.

1. Terms. From the served plan catalog: includedUsd, stepSizeUsd, and a step price. Free and Enterprise carry no band, so the payload answers active: false with no usage keys.
2. Period. The UTC calendar month containing now, as YYYY-MM.
3. Used. Workspace month-to-date spend: SUM(spend_micro_usd) from rollup_daily where day >= first of month AND day < first of next month. This is the same aggregate the dashboard total and workspace caps read. Per-request cost comes from the meter; see spend.
4. Step rate lock. The first read in a period inserts (workspace, period, step_micro_usd) into band_step_locks with ON CONFLICT DO NOTHING, then reads the stored value back. A catalog change mid-period does not move it. The next period locks the new rate.
5. Steps. over = used - included. If over <= 0, steps is 0. Otherwise steps = (over - 1) / step_size + 1, integer division. Ceiling, so entering a step counts it.
6. Overage. steps * locked step price, integer, display only. used and overage render in whole cents, half away from zero; usedMicroUsd and overageMicroUsd are the integers.

Worked example. Team, one UTC month, $12,000.00 routed.

(4,500,000,000 - 1) / 5,000,000,000 = 0, plus 1, is 1 step. Overage is 1 x 60,000,000 = 60,000,000, shown as $60.00 on the band tile and charged nowhere. Two edge checks: 7,500,000,000 used is 0 steps, and 7,500,000,001 used is 1 step.

The underlying rows chain under recovea-chain-v1, the only recipe production writes.

What it does not include

• Traffic that did not pass through our gateway.
• Requests refused before a provider call. There is no usage to price.
• Requests we could not price. They add zero, which understates the position.
• Provider discounts, credits, committed-use terms, and taxes. The band measures list price.
• Your Recovea subscription fee, which is not routed spend.
• Any per-key or per-project view. The band is one workspace total.
• Savings of any kind. This number is spend.

Limits and current status

• Enforcement. Not shipped, by construction. No code path attaches band overage to an invoice, and no metered price is attached in Stripe. Any future enablement carries 30 days of notice, applies prospectively from renewal, and cannot be retroactive.
• Two implementations, one served. crates/billing/src/band.rs holds the crossing event, the enforcement-notice descriptor, and the Retroactivity::Never type, and is not on the served path. The endpoint reimplements the same ceiling arithmetic in crates/platform/src/billing.rs. Both are tested and agree, but no crossing event is emitted anywhere today, so there is no crossing notification or email.
• Period alignment. The band window is the UTC calendar month. The stored subscription period end is not used here, so on an annual or mid-month subscription the band window and the invoice window differ.
• Budgets. Only workspace-scoped caps reach the gateway. Key- and project-scoped caps store but are not enforced yet.
• Alerts. The sweep runs about once a minute, so a fast burst can reach a cap between checks. Alerts warn on the way up. They are not an ordering guarantee.
• Counterfactual. Measured, never applied. Levers are not activated in any deployed environment, so none has changed a request or the band position.
• CPSO. Served at list price. Invoice reconciliation at period close is planned, not wired.
• Score. The engine is not shipped. No workspace has a score today.
• Spend and attribution drift. The band reads rollup_daily, the by-model cut and CPSO read receipts, attribution cuts read rollup_cuts. Same events, three layers, and no job continuously proves they agree. Receipt and rollup are separate writes, so a rollup failure after a receipt lands leaves that spend out of the band while the receipt stands. Receipts are the record of truth. Separately, two plan catalogs exist in the tree with different workingNumbers defaults; the band payload serves the platform one, where the flag is false.

Where to check us

1. Export the period: GET /platform/v1/ledger/export?period=YYYY-MM&format=jsonl. Rows carry costMicroUsd, priceListVersion, previousHash, and rowHash. The key-authed GET /v1/ledger/export serves the same rows in snake_case — price_list_version, previous_hash, row_hash — with the integer micro-USD under cost in JSONL and JSON and under the cost_micro_usd column in CSV.
2. Sum costMicroUsd across the export and compare with usedMicroUsd from the band payload for the same month. They should agree to the micro-USD. If they do not, a rollup write is missing; send us the request ids.
3. Re-derive the steps from usedMicroUsd, includedUsd, stepSizeUsd, and stepMicroUsd in that same payload, using the integer arithmetic above.
4. Check the billing claim directly: overageBilled is false, and GET /platform/v1/billing/invoices carries no overage line for any period.