Skip to content

Pricing and accounting architecture

CloudService 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: official model rates, cache ignored. This drives credit deductions, token/credit limits, 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

text
Customer input  = total input tokens / 1,000,000 × official input rate
Customer output = output tokens / 1,000,000 × official output rate
Customer total  = input + output (cache never discounts this)

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

Token allowance = total input tokens + output tokens

Cached input is a subset of total input; it is not added a second time. If the provider does not return exact cache counters, CloudService records cache availability as unknown and does not estimate a provider cost.

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 cloudservice setup is the automation path that can safely edit local client configuration files. Both use the same key identity and model catalog.