Multi-tenant billing with audit requirements

Tenant isolation is a workflow boundary, not only a table boundary

Treat tenant identity as a first-class field that survives ingestion, aggregation, invoice generation, exports, and operator tooling. Many isolation failures happen after the first request, when the boundary disappears inside jobs and retries.

• Every row, queue message, and background job carries the tenant identifier.
• All idempotency keys are scoped per tenant to avoid cross-tenant collisions.
• Admin tooling enforces tenant context and makes cross-tenant access explicit.

Audit trails should answer who, what, when, and why

Auditors, support teams, and security reviewers all want the same thing: a timeline that explains how a number was produced and who changed it. Keep billing actions append-only and store the inputs behind each invoice line.

• Log pricing changes and their effective dates.
• Log privileged actions such as refunds, credits, and manual adjustments with reason codes.
• Keep reconciliation artifacts when recomputation changes an outcome.

See the minimum boundary enterprise reviewers expect

The diagram below shows the tenant context that has to stay intact from request entry through background work and audit evidence.

Operate per tenant so one customer cannot destabilise another

• Use per-tenant rate limits and backpressure so a noisy customer does not starve the system.
• Keep deterministic reprocessors that can run per tenant and per billing window.
• Scope webhook dedupe and retry safety by tenant and provider account.