Diff-based engine

Orb’s diff-based billing engine enables backdated changes, safe migrations, and atomic previews—capabilities that traditional billing systems cannot support. This architecture ensures billing modifications are reversible, auditable, and always correct.

---

​

The problem with traditional billing

Most billing systems assume changes happen in the future. You schedule a plan change for next month. You add an add-on starting tomorrow. Everything flows forward in time. But real business doesn’t work that way:

• A sales rep closes a deal on Monday but the contract was signed Friday
• A customer calls to complain and you need to backdate a discount
• You discover a pricing error from two weeks ago that affected 50 customers
• An enterprise contract requires a commitment that should have started last quarter

Traditional systems handle these cases poorly—or not at all. Engineers write one-off scripts. Finance creates manual adjustments. Data integrity suffers. Orb’s diff-based engine treats every change as a comparison between “what should exist” and “what currently exists,” then applies only the difference. Past, present, or future—the same mechanism handles all cases.

​

Principles for safe subscription management

Orb’s architecture is grounded in two core principles:

1. Explicit timing for all actions
   • Every action—whether it’s a usage event, subscription edit, or cancellation—is attached to an explicit timestamp, not just the “current time.”
   • This prevents subtle errors, especially around billing period boundaries. For example, canceling a subscription at the end of the month should not risk overcharging a customer just because the request crossed a midnight boundary.
   • With Orb, you always control the effective time of every action, ensuring outcomes match your intent.
2. Reversibility and backdating
   • All actions are reversible whenever possible. You can undo a scheduled cancellation, extend a trial, or change a contract ramp at any time—unless there are end-user-facing side effects (like a sent invoice or email), in which case Orb issues credit notes to correct the record.
   • Orb is built to support backdated actions: the system “rewinds time” as if the action happened at the specified date, then automatically plays forward the consequences to catch up to the present.

​

How the diff engine works

When you make any change to a subscription—add a price, apply a discount, backdate a cancellation—Orb doesn’t directly manipulate invoices. Instead:

1. Compute expected state: Given the subscription parameters (prices, timing, configuration), what invoices should exist?
2. Compare to actual state: What invoices currently exist in the database?
3. Calculate the diff: What needs to be created, modified, or removed?
4. Apply atomically: Create new invoices, void or credit existing ones, update the ledger—all in a single transaction

The engine computes an InvoiceDiff containing:

• Invoices to create (with full line item details)
• Invoices to remove (draft invoices are deleted; issued invoices are voided or refunded)
• Invoices to edit (for in-place modifications to draft invoices)
• Credit notes to issue (for refunding portions of paid invoices)
• Ledger entries to adjust (for prepaid credit rebalancing)

The diff is validated, then applied atomically. If anything fails, nothing changes.

​

Why this matters: real-world scenarios

​

Backdated subscription creation

A customer signs a contract on March 15th, but their service started March 1st. You create the subscription with a start date of March 1st. What happens:

1. Orb computes what invoices should exist for March 1-15
2. If usage occurred during that period (events with timestamps in that range), it’s automatically included
3. Invoices are created with the correct service periods
4. Revenue recognition reflects the actual service dates

No scripts. No manual adjustments. The subscription exists as if it had been created on time.

​

Mid-period cancellation with refund

A customer cancels on March 20th, but they paid for the full month upfront. What happens:

1. Orb computes the expected state: subscription ends March 20th
2. The diff shows: existing invoice overstates the service period
3. Orb issues a credit note for the unused portion (March 21-31)
4. The credit goes to customer balance for future invoices (or refund if configured)

The original invoice remains unchanged for audit purposes. The credit note records the adjustment.

​

Pricing error affecting multiple customers

You discover that 50 customers were on the wrong plan for the past two weeks. What happens:

1. You correct each subscription’s pricing (or run a migration)
2. For each customer, Orb computes the diff between old and new pricing
3. Draft invoices are updated in place
4. Issued invoices get credit notes or voids as appropriate
5. Revenue reports automatically reflect the corrections

Same mechanism, applied 50 times. No special handling required.

​

Atomicity enables previews, dry runs, and pending changes

A unique advantage of Orb’s atomic, diff-based architecture is that every change is a pure, replayable calculation. This means:

• Previews of any endpoint are possible: Because the system can deterministically simulate the effect of any change without side effects, you can preview the result of any API call—whether it’s a subscription mutation, pricing update, or usage event—before committing it.
• Dry runs: Orb’s dry run feature lets you validate requests and see their impact without making any actual changes. The system computes the outcome as if the change were real, but nothing is persisted.
• Pending changes: With pending changes, you can stage a subscription change, preview its effects (including invoice previews), and only apply it when you’re ready. This is possible because Orb can always calculate the post-change state without mutating the underlying data until you commit.

This atomicity and replayability are only possible because Orb never mutates state as a side effect of an API call. Instead, every change is a transaction that can be previewed, staged, or rolled back, giving you full control and confidence in your billing operations.

​

Versioned plans and safe, scalable migrations

Orb’s architecture also enables first-class support for plan versioning and bulk migrations—capabilities that are difficult in traditional billing systems.

• Versioned timelines: Every subscription in Orb is a timeline of price objects, each with a start and (optionally) end date. When a plan changes—such as adding an add-on or rolling out new pricing—a new version is created, and the system tracks the lineage and differences between versions.
• Immutable auditability: Plans themselves are immutable; instead, new versions are layered on, ensuring a clean audit trail for every change. This means you always know exactly how each invoice was generated, and can trace changes over time.
• Atomic invoice regeneration: When a subscription migrates to a new plan version, Orb atomically re-generates the set of invoices that should exist, based on the new timeline. This is the same diff-based mechanism that powers all other changes, ensuring migrations are safe and idempotent.
• Flexible effective dates: Migrations can be scheduled to take effect at any date—immediately, at a specific future date, or aligned to each customer’s next billing cycle. Orb’s primitives allow maximum flexibility, so you can roll out pricing changes exactly when and how you want.
• Immediate, scalable propagation: All migrations are applied immediately to the subscription’s state, regardless of the effective date. This ensures that upcoming invoices always reflect the correct pricing, and previews are accurate. Even for large-scale migrations across millions of subscriptions, Orb guarantees correctness and consistency.

This approach eliminates the need for risky migration scripts, manual data dumps, or overnight batch jobs. Instead, migrations are safe, auditable, and fully integrated into the billing engine’s atomic, diff-based model.

​

What this guarantees

The diff-based architecture provides concrete guarantees that traditional billing systems cannot match: These aren’t aspirational goals. They’re consequences of the architecture. The diff-based approach makes entire classes of billing errors structurally impossible.