Query-based billing

Orb’s billing engine treats billing as the output of a deterministic query, not a side effect of streaming state mutations. This architectural choice eliminates entire classes of billing errors and enables capabilities impossible in traditional systems.

---

​

The fundamental difference

Most billing systems process usage events as they arrive, incrementing counters and updating aggregations in real-time. This seems efficient, but it creates a fundamental problem: once an event is processed and the counter is incremented, the original context is lost. If pricing changes, if events arrive late, or if a mistake needs correction—there’s no safe way to recalculate. Orb takes a different approach. Every usage event is stored immutably in a columnar data store. When generating an invoice, Orb executes a fresh query over the raw event data, applying the current metric definitions and pricing configuration. The invoice is computed, not retrieved. This means:

• The same query, run twice, produces the same invoice—true determinism
• Late-arriving events don’t corrupt existing state—re-query to get the correct answer
• Pricing changes can be applied retroactively—the historical events are still there
• Every line item is traceable to specific events—complete auditability

By decoupling invoicing from ingest‑time side effects, Orb eliminates errors such as double‑counting, drift between counters and source data, and silent corruption.

​

Core concept: billing as a query

Billing is treated as a pure function. Usage events are stored immutably. When generating an invoice, Orb queries:

“Given this customer, this billing period, and this subscription and pricing configuration, what should the invoice look like?”

Invoices are derived from:

• Raw usage events: All usage data is stored immutably and forms the foundation for invoice calculation.
• Immutable metric definitions: Metrics themselves are immutable. If usage events need to be amended, Orb applies amendments as a read-path overlay, layering corrections or changes on top of the original events to calculate the correct set of events to honor.
• Versioned pricing objects: Pricing changes are tracked over time, supporting accurate billing for any period.
• Versioned subscription timelines: Subscription changes are recorded as timelines, allowing for precise reconstruction of billing states.

This model provides the following benefits:

• Deterministic results: The same inputs always yield the same output, ensuring consistency and predictability.
• Full auditability: Every line item is traceable to its underlying usage and configuration, supporting robust audits.
• Safe backfilling: Delayed data or configuration fixes can be re-run safely without risk of corruption.
• Simulation capability: Pricing changes or plan migrations can be tested before being applied, enabling safe experimentation.
• Scalability: Heavy computation is performed offline, so production traffic is not impacted by expensive aggregations.

​

Just-in-time invalidation and invoice computation

Orb does not run full-period queries only at invoicing time. Instead, a dependency graph and invalidation system track how each invoice fragment depends on usage, pricing, and configuration. When relevant data changes—such as a late-arriving usage event, plan migration, or pricing update—only the affected invoice fragments are invalidated. When an invoice is generated, Orb computes only the invoices and fragments that are out of date, based on the latest state. This approach provides:

• Efficiency: Only the minimal set of invoices are recomputed, even as data changes across millions of subscriptions.
• Correctness: Every invoice reflects the latest, correct state, regardless of the number of changes or corrections.
• Safety: The system is idempotent and auditable, with every change traceable and reversible.

This invalidation and dependency-tracking mechanism enables high-scale, real-time billing operations without sacrificing accuracy or auditability.

​

Why this matters — real‑world impact

Most billing platforms mutate counters when events are ingested. This makes backfilling difficult and corrections risky. Orb’s architecture avoids these problems by not relying on pre-aggregated counters. If pricing changes, usage is delayed, or a subscription is misconfigured, Orb allows the inputs to be fixed and billing to be re-run. This is not possible in stream-mutation systems without manual intervention.

​

For finance teams

• Month-end close in hours, not days: When you close an accounting period, the numbers are final. If billing activity occurs for a closed period, Orb automatically applies catch-up adjustments to the next open period—no manual journal entries.
• Every number is auditable: Drill from a revenue line item down to the specific events that generated it. No black-box calculations.
• Corrections without fear: Issuing a credit note or voiding an invoice doesn’t corrupt downstream reports. The system recalculates from source data.

​

For engineering teams

• Safe backfilling: Discovered that events from three days ago were missing? Backfill them. The invoices recalculate correctly.
• No migration scripts: Pricing changes don’t require data migrations. The new pricing logic applies to historical events automatically.
• Testable billing logic: Preview any invoice before it’s issued. Simulate pricing changes against historical data. Know exactly what will happen.

​

For product teams

• Iterate on pricing: Test new pricing models against real usage data before rolling them out. See the revenue impact for every customer.
• Launch faster: New billable metrics can be defined retroactively—no need to instrument first and wait for data to accumulate.

​

Real-time without compromise

A common objection: “If you’re querying raw events, how can you support real-time use cases?” Orb runs two parallel systems: The stream-based system maintains running totals in Redis (MemoryDB) as events arrive. When a threshold is crossed, webhooks fire immediately. But the billing logic never touches these counters—invoices are always computed from raw events. This dual architecture means you get both:

• Real-time operational signals for product experiences
• Accurate, auditable invoices that can be reconstructed from first principles

​

How the dual pipeline works

1. Event arrives via the ingestion API
2. Stream pipeline updates cached metric values in Redis, checks alert thresholds
3. If threshold crossed, webhook fires within seconds
4. Raw event is written to the columnar store
5. At invoice time, billing queries the columnar store directly—never the cached values

The cached values are an optimization for speed. The raw events are the source of truth for accuracy.

​

Scale and performance

• Event ingestion: Native capacity of 1,000+ events per second, with hosted rollups available for higher volumes
• Alert latency: Seconds from event to webhook for incrementally computable metrics (SUM, COUNT)
• Invoice computation: Heavy computation runs asynchronously, never blocking your API calls
• Tested at scale: Field-tested with companies processing millions of events per second

​

Raw data, high‑throughput analytics

All usage events are stored in a columnar OLAP store. This provides:

• High throughput: Production clusters sustain much higher throughput than typical OLAP stores.
• Flexible analytics: Query raw events via Orb’s SQL‑powered API to break down usage by any property.
• Retroactive metrics: Define a new metric and calculate it back to day zero without re‑ingesting data.
• Simulation: The same raw dataset powers Orb Simulations, replaying historical events through hypothetical pricing.

Because the source of truth is immutable event history—not lossy counters—flexibility is not traded for scale.

​

The bottom line

Traditional billing systems make trade-offs: you get either speed or accuracy, either flexibility or scale. Orb’s architecture refuses these trade-offs. This is the foundation for billing you can trust: reproducible calculations, immutable history, and the flexibility to evolve your pricing without fear.