Pricing and accounting architecture

ScaleMax separates customer billing, provider cost, and raw token accounting. Every completed request stores all three views at request time, so a later price change cannot rewrite historical usage.

Three independent ledgers

• Customer ledger: published model rates. When a model publishes a customer cache-read or cache-write rate and the provider reports an exact split, that bucket uses its published rate; otherwise input uses the ordinary published input rate. This drives credit deductions, invoices, and customer dashboards.
• Provider ledger: private provider input, cache-read, cache-write, and output rates. This is admin-only and drives profit and margin.
• Raw token ledger: total input, uncached input, cache counters, output, and provider-total tokens exactly as returned by the provider.

Formulas

Customer uncached input = uncached input tokens / 1,000,000 × published input rate
Customer cache read     = cache-read tokens / 1,000,000 × published cache-read rate (or input rate when none is published)
Customer cache write    = cache-write tokens / 1,000,000 × published cache-write rate (or input rate when none is published)
Customer output         = output tokens / 1,000,000 × published output rate
Customer total          = uncached input + cache read + cache write + output

Provider total = uncached input cost + cache-read cost
              + cache-write cost + output cost

Token allowance (raw) = total input tokens + output tokens
Token-key debit       = uncached input + cache write + output + (cache read × applicable allowance rate)

Claude cache-read allowance rate = 0.10×
GPT/Fable cache-read allowance rate = 0.25×
Other model families = 1.00×

Cached input is a subset of total input; it is not added a second time. The raw ledger always preserves the provider total. The token-key cache-read allowance rate only changes the prepaid allowance debit: cache writes, uncached input, and output remain full-count. If the provider does not return exact cache counters, ScaleMax records cache availability as unknown, omits cache fields from native Claude streaming telemetry, and does not invent a discounted split.

Effective-dated rates

Frontend rates live in model_frontend_pricing and provider rates live in model_provider_pricing. Insert a new effective-dated row for a future change. The request stores the selected row and rate snapshot permanently.

Frontend and provider large-context thresholds are independent. Each ledger switches tiers only when its own threshold and complete tier rates are present. Monetary arithmetic uses integer micro-USD to avoid floating-point drift.

What customers and admins see

Customers see frontend credits, customer-visible tokens, model, and remaining allowance. Provider rates, cache cost, backend total, revenue, and margin remain admin-only. Admin usage analytics shows each backend component and labels unavailable cache data as unknown.

The customer-facing side of these ledgers is documented in Billing, API credits & token packs; the per-model rates they apply are listed in Models and pricing; and a single key's recorded totals can be read from the Usage Checker.

Migration and corrections

Migration 0056_three_ledger_pricing.sql adds the versioned tables, canonical request fields, indexes, and immutable correction/audit workflow. Historical cache values are marked unavailable when the old row did not contain them; they are never guessed. Corrections use an audited correction record rather than editing or deleting a usage row.

Web versus terminal setup

The web guided setup wizard is the cross-subdomain checklist: it detects the active key’s billing mode and scope, shows the matching base URL, and links to browser apps and client documentation. The terminal command scalemax setup is the automation path that can safely edit local client configuration files. Both use the same key identity and model catalog.