Usage & billing policy

The Business program defines what is metered, billable, limited, and granted. The platform records the runtime decisions and settlements produced by that contract. Keep those ownership boundaries separate while diagnosing.

Start with the accepted contract#

farthershore business status acme --format json
farthershore business routes acme --env production --format json
farthershore business contract acme --env production --format json
farthershore plan list acme --format json

Confirm the expected release is live and the route, meter, and plan version you expect were actually accepted. A local source file or pending Git commit is not runtime evidence.

Follow live traffic#

farthershore analytics timeseries acme --range 24h --domain usage --format json
farthershore analytics top acme --range 24h --by type --domain usage --format json
farthershore analytics latency acme --range 24h --format json
farthershore analytics log acme --range 1h --domain usage --limit 100 --format json
farthershore usage summary acme --format json

• Timeseries shows volume over time.
• Top groups current activity by the selected dimension.
• Latency distinguishes application slowness from missing traffic.
• Log is the newest-first request and metering evidence.
• Usage summary is the coarser 30-day business view.

Use --env <environmentId> on analytics when you need an exact environment. Do not combine preview usage with production billing conclusions.

Explain a denial#

farthershore denial show acme <requestId> --format json

Correlate the denial with the request id and decision id from the gateway response. See Diagnose limits and denials.

Compare the full chain#

When served requests and billed usage disagree, compare in order:

1. Accepted commercial release, route match, and environment.
2. Gateway request/decision record (its signed usage event carries the served identity: subscription, release, rating context).
3. Backend report() for backend-measured dimensions — measure keys and dimension values must match the release's measurement schema.
4. Aggregated usage summary.
5. The rating context the event was admitted under, its RatedCharge, and the funding postings — the subscriber's bill preview is computed from exactly these.

A missing event near the start of that chain cannot be repaired by changing a price. An unexpected price cannot be repaired by replaying traffic — usage is rated under the release it was admitted with, never at today's catalog. Find the first boundary where evidence diverges. If the ledger and Stripe disagree, the subject is in RECONCILIATION_REQUIRED and monetary admission is blocked until reconciliation clears it; see Ledger & settlement.

The CLI also exposes a preview-only historical billing replay:

farthershore workflow-control replay acme \
  --period-start 2026-08-01T00:00:00Z \
  --period-end 2026-09-01T00:00:00Z \
  --format json

This previews historical replay work; it does not execute a charge or mutate a provider. Treat its result as diagnostic evidence.

If the accepted contract is wrong, fix business/, test in preview, and publish forward. If the contract and request evidence are correct but settlement or provider state diverges, capture request ids, decision ids, subscription ids, period bounds, and the live release for support.