Managing customer subscriptions involves creating them when service starts and executing changes via add-ons, upgrades, or downgrades. These actions may happen manually in a billing admin view or programmatically through your product dashboard, triggered by the end user.

Most billing systems are designed for the happy path: changes are scheduled for the future or happen on time as desired. In reality, changes often need to be undone or made effective as of a past date. Orb’s diff-based billing engine is designed to handle these real-world complexities safely and automatically.

​
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

Orb’s diff engine makes this possible by:

  1. Generating the invoice implied by the current model and usage, as of any point in time.
  2. Diffing that against what was previously issued.
  3. Applying only the delta—issuing new invoices, voiding or crediting prior ones as needed.

​
Why this matters: real-world scenarios

This architecture enables:

  • Accurate migrations: Subscriptions can start at the correct historical date, and Orb will instantly create the invoices and fill them with the required usage information.
  • Backdated contract changes: When you sign an enterprise contract and need to backdate a discounted pricing structure or prepaid commitment, Orb automatically re-prices existing usage on elapsed invoices.
  • Error correction: If you make a mistake with a customer’s pricing and no invoices have been issued yet, you can correct it without incident. If invoices have already been issued, Orb will void and re-issue all relevant invoices to reflect the change.

​
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.