Eng Deep Dive

22 min read

The evolution of Orb's billing engine

Written by

Senior Engineering Manager

Orb's billing engine has gone through several iterations around one question: where should a price be tracked? This is the history of those iterations, what each one taught us, and why they result in a billing engine that is both flexible and safe.


At Orb, we call the core of our product the billing engine. It's the system that keeps track of what each end customer (the person or organization an Orb customer bills through Orb) pays, applies pricing changes, and turns usage and fees into invoices. Many other parts of Orb read from it, including credits, alerts, and revenue reports. For every end customer at every point in time, the billing engine answers one question: what should this customer be charged, and why?

We have a phrase for this internally: billing must be correct. It's a reminder of the care we take with every change to the billing engine. An invoice that's wrong costs an Orb customer either revenue or their end customer's trust (and frequently both).

Meeting that standard is more difficult than it looks, and we made T-shirts internally to remind ourselves of it:

FIG 1. A daily reminder of the seriousness of billing (and the unseriousness of our T-shirt fonts).

Billing looks easy because the first version of the model is simple. Orb's was too: a customer subscribes to a plan, and the plan holds every price that customer pays. That model is easy to explain and easy to build, and it stays correct for as long as every end customer on a plan pays the same thing.

That stops being true quickly. Sales negotiates a lower rate for one end customer. Another end customer buys an add-on halfway through the month. Pricing changes for everyone on a plan, but each end customer needs the change on their own renewal date. The same price for LLM Tokens shows up in a dozen plans, and nothing records that it's one centralized price. Each of these scenarios asks the billing engine to keep a price somewhere other than inside a single plan.

So where should a price be tracked? Orb has given six answers since 2021:

FIG 2. Six answers to where a price lives. Peach marks a copy; heather marks a recorded reference. The later steps replace copies with references.

Year

Where the price lives

What changed

2021

Inside the plan

The plan owned every price, and every subscriber paid the same thing.

2022

In a copy of the plan

A negotiated deal created a private copy of the plan with the overridden values.

2023

On the subscription, as price intervals

A subscription became a timeline of prices, each with its own start and end.

2023–24

In numbered plan versions

Plans gained a history, and migrations moved subscriptions between versions.

2024

On the subscription, as a difference from the plan

An override stopped being a copy and started recording the price it replaces.

2026

In a shared Pricebook

Plans and subscriptions reference a price instead of owning one.

Most of these steps gave Orb customers more flexibility, and two kinds of copies came along the way. Orb copied the plan for each negotiated deal, and because every plan owned its prices, Orb customers copied the same price into every plan that charged for it. Copies are easy to change, but a copy usually doesn't record what it changed relative to its source, so these copies made a few questions harder to answer. Which end customers are paying list price? What will this pricing change touch? In both cases, a later step made that flexibility safe again, first by recording what each override changed and then by replacing repeated prices with one shared price. Underneath all of it, every iteration had to leave invoices that were already sent as they were, unless deliberately corrected.

The rule I've taken from this history is that copies are frequently the fastest way to give a billing engine flexibility. To keep that flexibility safe, you need to record references where possible. Flexibility and safety tend to push up against one another.

2021

The plan owned everything

Orb's first pricing model was the textbook one. An Orb customer defined a plan (say, a Starter Plan with a $500 monthly Platform Fee and $0.01 per LLM token), and each of their end customers got a subscription to that plan. Every price belonged to a plan, and a price could not exist without one. A subscription was a sequence of plans over time, and the billing engine decided which invoices to create by looking at which plan the subscription was on, and for how long.

This model had real strengths. Every subscriber on the Starter Plan paid the same prices, so the question "who pays what?" was answered by "which plan are they on?". Plans were also intentionally immutable. Once an invoice had been generated from a plan, editing that plan in place would make it impossible to explain how the old invoice was calculated.

The problem is that pricing rarely stays this uniform. The first enterprise deal, say for Acme Corporation, showed up with a negotiated rate of $0.008 per LLM token, and the modeling didn't have a place to store it. The only option was another plan containing a single customer, something like "Starter Plan (Acme Corporation)". In Orb's earliest days that's exactly what happened.

2022

Overrides as copies of the plan

In early 2022, Orb added optional overrides to subscriptions, so an Orb customer could change the rate on any of the plan's prices or add a discount. Plan phases followed a couple of months later for ramp deals, and scheduled quantity changes for fixed fees arrived late in 2022 for seat counts that grow over a contract.

Under the hood, an override created a copy. Because the billing engine generated invoices from plans, a subscription with different pricing needed a plan of its own. Orb copied the whole plan into a new child plan that pointed back to the original plan, applied the overridden values to the copied prices, and pointed the subscription at the child plan.

Price

Starter plan

Acme Corporation's child plan

Platform fee

$500 / month

$500 / month (copied)

LLM Tokens

$0.01 / token

$0.008 / token (copied, then edited)

A child plan let invoicing, usage queries, and reporting work unchanged, and it shipped per-customer pricing with very little new machinery. I think it was a simple and pragmatic choice at the time.

The tradeoffs showed up later. The child plan's LLM Tokens price is a brand-new price that happens to hold a different rate. The child plan knew which plan it was copied from, but no mapping existed to record that its LLM Tokens price was the Starter Plan's LLM Tokens price with a negotiated rate of $0.008 instead of $0.01. That made two questions surprisingly difficult once Orb customers had thousands of subscriptions:

  • Which Starter Plan end customers pay list price, and which negotiated a different rate? To answer this, you had to compare every child plan against its parent on a price-by-price level.
  • When changes to pricing occur for the Starter Plan, what should happen to Acme Corporation? Because plans were immutable, new pricing meant a new plan, and Acme Corporation's copy stayed behind.

2023

The subscription becomes a timeline of prices

The next set of requests didn't fit inside a plan at all, even a copied one. The first push came from requests to sell add-ons. An end customer adds a Premium Support add-on on April 16th. Another gets 20% off in June to make up for an outage. A third has a rate change that starts next month for them and nobody else. Each of these is a change to one subscription, starting at one point in time, that has nothing to do with the plan.

In 2023, we remodeled the subscription so that it, rather than the plan, is the source of truth for invoicing. A subscription became a timeline of price intervals: each one is a price, a start time, an optional end time, and its own billing cycle settings. In 2024, discounts, minimums, and maximums followed as adjustment intervals with the same shape. When a subscription is created, Orb creates its intervals from the plan's prices. From then on, the plan is where those intervals came from, rather than something invoicing reads at billing time.

The price intervals API exposes this directly: an Orb customer can add, edit, or end intervals on any subscription, effective in the past, the present, or the future. The subscription editor in the Orb web app does the same with a preview. Here's what Acme Corporation's subscription would look like if it received both the Premium Support add-on and the June discount:

FIG 3. A subscription as a set of intervals. Adding Premium Support adds one row and leaves the Platform Fee and LLM Tokens untouched; the June discount starts and ends on its own. (Discounts joined the timeline as adjustment intervals in 2024.)

Each row in Fig 3 is independent. Adding Premium Support on April 16th doesn't touch the Platform Fee or LLM Tokens prices. It adds one more interval that starts mid-month and has no end.

In my view, this was the step that added the most flexibility. A subscription can now hold any combination of prices over any period of time, independent of every other subscription on its plan. It also made the plan less authoritative. Once Acme Corporation's subscription has its own intervals, changing its pricing means updating each interval, not just pointing the subscription at a new plan. That raised the obvious next question: how does an Orb customer change pricing for everyone?

2023-2024

Plans get versions

One of the most common questions pricing teams started to ask was: "How do I change a price for everyone on the Starter Plan?" With immutable plans, the answer used to be to create a new plan and schedule a plan change for each subscription, one at a time, frequently with a script written by an engineer and run overnight. That was tedious, and it left Orb customers with many slightly different plans.

Plan versions and migrations give a plan a numbered history, and they edit only the prices that actually changed. Plans started at Version 1 when they were initially created. Version 2 could raise the LLM Tokens price to $0.012 and add a new Storage price. Publishing Version 2 can make it the default for new subscriptions, and existing subscriptions stay on Version 1 until they're migrated. There were two explicit design decisions for plan versions that made this safe.

1. Versions record the difference

Version 2 records a diff of what has changed between itself and Version 1. Its LLM Tokens price replaces Version 1's, Storage was added, and nothing was removed. A migration applies exactly that difference to each subscription's timeline at the effective time, and leaves every unchanged price, and its billing period, alone. Recording a replacement also captures intent. Imagine Version 1 of the Starter Plan also included a Support price, and Widgets Inc. had that price removed through a subscription edit. If Version 2 changes the Support price, Orb knows the new Support price is a replacement for the old one rather than a new addition, so the migration leaves it off Widgets Inc.'s subscription. A plain before-and-after comparison of two price lists loses that intent and adds the price back.

2. Changes take effect with subscription-relevant timing

A plan version migration can be run against subscriptions on a given plan, moving them from one version of that plan to another. These migrations can take effect at various times, including:

  • Immediately.
  • On a specific date.
  • At the start of each subscription's next billing period.
  • Backdated to the start of each subscription's current billing period.
FIG 4. One version change, three effective times. Subscriptions migrated at their next billing period switch on the 7th and the 13th, so neither changes mid-period. A subscription migrated with backdated timing switches at the start of its current period, June 1st, even though the migration was scheduled on June 20th.

As Fig 4 shows, with the next billing period option, a subscription that bills on the 7th of the month and another that bills on the 13th each move on their own boundary, so pricing changes don't appear in the middle of a billing period. Orb also applies a migration to each subscription's intervals when the migration is scheduled, rather than waiting until the effective date, so upcoming invoices and previews already show the new pricing. A migration could be scheduled right as an invoice is about to be issued, so before issuing any invoice, Orb checks the subscription for pending migrations and applies them first.

Backdating matters more than it sounds. Contracts are frequently signed after the date they take effect, and a pricing team may decide in the middle of a month that a new usage rate should apply to the whole month. Migrating at the start of the current billing period means usage-based changes land on the invoice that's already in progress, without an extra invoice. When a change reaches back past invoices that have already been issued, Orb recalculates the affected invoices and reissues them, rather than leaving the difference to a spreadsheet and a manual credit. I covered how that works, and why it's difficult, in The two clocks of billing.

Plan versions also showed why child plans had to go. With plan versions, pricing could evolve over time, but a subscription on a child plan was stuck: one custom negotiated rate meant all of its pricing lived on a copy that new versions couldn't reach. Keeping individual overrides in place while rolling pricing out broadly took the next step.

2024

Overrides become differences

By mid-2024, the child plan was the weakest part of the model, and price intervals had removed the reason for it. Child plans existed because invoices were generated from plans. Once invoices were generated from the subscription's timeline, an override could simply be a change to that timeline.

We also realized that an override is the same kind of thing as a plan version change. Both are a difference (add these prices, remove those, replace this one with that one) applied to a subscription's timeline at a point in time. An override at subscription creation is that difference applied when the subscription starts. So overrides now go through the same code as plan version migrations, and Orb stores each subscription's differences from its plan instead of inferring them later.

Today, an override is a price on the subscription that records which plan price it replaces, and the subscription stays on the Starter Plan itself. In September 2024, the create subscription API gained add_prices, remove_prices, and replace_prices, which describe a deal in exactly those terms.

FIG 5. The same negotiated rate, stored two ways. On the left, the relationship between $0.01 and $0.008 has to be recovered by comparing two plans. On the right, it's stored.

The change sounds small, but it helped make answering questions about list prices much easier. "Which Starter Plan end customers pay list price?" becomes "which subscriptions on the Starter Plan have no recorded differences from it?". What the sales team agreed to in the contract is stored rather than recomputed. And because both overrides and plan versions record replacements, Orb defines a few mechanics to make them operate consistently during a migration:

The override

The new version

The migration

Removed a price

Replaces that price

Doesn't add it back

Replaced a price

Also replaces it

Leaves the overridden price alone

Replaced a price

Removes it

Removes it

Moving existing subscriptions off child plans was more involved than stopping the creation of new ones. Orb converted existing subscriptions back onto their parent plans, rewriting each child plan as a set of differences and keeping a record that maps every copied price to the price that replaced it. Orb customers had years of invoices generated from child plans, and those invoices needed to keep explaining themselves.

2026

Prices leave the plan

After all of this, one kind of copy remained: the same price defined separately in several plans. An Orb customer with Starter, Pro, and Enterprise plans that all charge for LLM Tokens has three LLM Tokens prices. They may hold identical numbers today, but they are three separate rows that can drift apart. Changing the list price of LLM Tokens means recreating the new rate by hand in each of the three plans, each through its own plan version and migration, and nothing in Orb records that those three prices are meant to be one price.

Pricebook, which Orb recently launched, removes that copy. It's a shared catalog of products and prices: a price is defined once, attached to a product, and plans reference it rather than owning a copy. The Starter, Pro, and Enterprise plans can all point at the same LLM Tokens price, and the catalog lists every plan that uses a price, so an Orb customer can see what a change would touch before making it.

FIG 6. The last copy removed. The list price lives in one place, and each override is recorded relative to it.

With a catalog in place, every override has the same reference point. The catalog holds the list price, every plan and subscription that references it bills that price by default, and a negotiated rate is an override on one subscription relative to the list price. Because each override is recorded against its base price, Orb can show every override next to the price it changes and the customer it belongs to. That makes it possible to see, directly in Orb, how many end customers pay something other than list, and at what rate. Notably, this matters more for companies that negotiate every enterprise deal, not less. Without a catalog, each negotiated deal becomes its own standalone price, and over time it becomes difficult to say what standard pricing even is.

The catalog itself was the straightforward part. Most of the difficult work happened underneath it, including:

  • Plans had to stop owning their prices, so that one price could belong to many plans.
  • Subscriptions had to track their plan phases explicitly, since a shared price can appear in more than one phase and no longer identifies a single one.
  • Dimensional prices, which split one billable metric into separately priced groups (by region or model, for example), needed rules to keep two shared prices from billing the same usage twice.
  • And much more.

Changing the engine without changing history

Each step above rebuilt part of the billing engine while it was billing real customers, and that creates a problem particular to Orb's design. The billing engine computes the invoices a subscription's timeline implies and compares them with the invoices that exist. So any change to how it computes invoices also changes what it believes past invoices should have been. Without care, an improvement to how amounts are rounded would show up as a difference against thousands of invoices that end customers have already received, and in many cases already paid.

That's why reproducibility is a hard rule for us: an invoice that's been issued must regenerate to the same result after the engine changes underneath it. We hold to that in three ways:

  • New behavior is gated by date. When we change how invoices are computed (for example, how amounts are rounded, or which charges are merged onto one invoice), the change applies from a cutoff date onward, and invoices before that date are still calculated the way they originally were (Fig 7).
  • New code runs beside the old before it replaces it. When we rebuilt how the billing engine derives the contents of an invoice, both versions ran side by side on real invoices in a comparison mode that records every mismatch, and we've been moving invoices over to the new version gradually.
  • Data model changes are double-written and backfilled before anything reads from them. The larger remodels in this post wrote both shapes for a while, backfilled existing data, and switched reads behind a feature flag that could be turned back off.

This makes changes to the billing engine slower, and it means the code carries old behavior for a long time after we've stopped wanting it. I think that's the right tradeoff. An invoice that changes after the fact, with no record of why, no longer matches what the end customer received; keeping that history is what the wall clock in The two clocks of billing is for.

A pricing change today

Orb customers run a scenario like this one frequently. An Orb customer sells LLM access on Starter, Pro, and Enterprise plans, all of which reference one LLM Tokens price in Pricebook at $0.01 per token. They have 3,000 subscriptions, and 200 of them have a negotiated LLM Tokens rate. They decide to raise the list price to $0.012, effective at the start of each subscription's next billing period. Separately, Globex Corporation signed a contract amendment on June 5th that moves it to the new rate effective June 1st.

  1. Create the new price in Pricebook. The $0.012 price is defined once. Before anything changes, Pricebook shows the three plans that reference the current price, so the scope of the change is visible up front.
  2. Publish a new version of each plan. Each version replaces the LLM Tokens price with the new one from the catalog. Each version records the replacement itself, so Orb knows the new price is the old price changed, not an unrelated new charge.
  3. Preview. Before migrating, the Orb customer can see how any individual subscription's upcoming invoices will change.
  4. Migrate at the start of each subscription's next billing period. A subscription that bills on the 7th moves on the 7th, and one that bills on the 13th moves on the 13th. Orb applies the change to each subscription's timeline right away, so the invoices for the next billing period, and previews of them, already show the new rate.
  5. Leave negotiated rates alone. The 200 subscriptions with negotiated rates have overrides that replace the old list price, so by the rules above, the migration leaves their negotiated rates in place. Because each of those overrides records the $0.01 price it replaced, those 200 subscriptions are a list in Orb rather than a spreadsheet, and the sales team can decide which ones to renegotiate.
  6. Backdate where the contract says so. Globex Corporation is also on one of these plans and pays list price. Instead of waiting for its next billing period with everyone else, it's excluded from the migration and migrated to the new version on its own, backdated to the start of its current billing period, which began on June 1st. Its June usage is billed at $0.012 on the invoice for June, with no extra invoice. If the amendment had reached back to May and May's invoice had already been issued, Orb would recalculate and reissue it.
  7. Keep the record. Every step leaves a record: the price and who created it, each plan version and what it replaced, and each migration and when it applied to each subscription. Six months later, "why did Globex Corporation pay $0.012 per token in June?" has an answer in Orb.

None of these steps needs manual work outside Orb, and none of them change an invoice that's already been sent without a record of the change. Each one depends on a lesson from the history above.

What we learned

Looking back, each step addressed something an earlier step made difficult. Two of those steps, overrides as differences and Pricebook, made the flexibility added by earlier steps safe again. Both did it by recording what a price is relative to, either the plan price an override replaces or the shared price a plan references.

Step

Flexibility it added

What was still difficult

What addressed it

The plan owns every price

Simple, uniform pricing

Any negotiated deal needs its own plan

Overrides as copies (child plans)

Overrides as copies (child plans)

Per-customer rates and discounts

Knowing who pays list price; new plans and versions don't reach the copies

Overrides as differences

Price intervals

Add-ons and discounts at any time, including backdated

Changing pricing for everyone on a plan

Plan versions and migrations

Plan versions

Bulk pricing changes with per-subscription timing

Migrating subscriptions that live on copies

Overrides as differences

Overrides as differences

Negotiated rates that survive migrations

The same price duplicated across plans

Pricebook

Pricebook

Define a price once and reuse it in any plan

-

-

The lessons we took from these iterations are the ones we now design new features around:

  • The subscription's timeline is the source of truth, and every change is a difference applied to it. Add-ons, overrides, migrations, and backdated changes all go through the same path, so each one is previewed, applied, and recorded the same way.
  • A change records its relationships, not only its result. "This price replaces that one" helps Orb understand intent. This is what lets an override survive a migration, and what lets a migration avoid re-adding a price an end customer had removed.
  • Changes are written to the subscription's timeline when they're made, even when they take effect later. Scheduling work to happen on a future date creates a window where previews and upcoming invoices can be wrong. Applying a change to the timeline when it's saved means they reflect it as early as possible, and Orb applies any pending migration before issuing an invoice.
  • Improvements to the billing engine don't rewrite history. New behavior applies going forward, and an issued invoice should regenerate exactly as it was sent.
  • Copies are allowed, but they record what they changed. Shipping the copy first is frequently the right call, as long as each copied price records which price it came from and what it changed. Where several plans need the same price, referencing one shared price is better still.

This is what we mean when we say Orb is flexible and safe. The two stop being in tension once the billing engine tracks what each change was made relative to. That record is what allows a price to be copied, overridden, added mid-term, or changed retroactively. Because those records exist, Orb can preview what a pricing change will do to each subscription before it happens, and then roll it out to thousands of subscriptions without manual work by the customer. Without the records, the same features become risky to use, leaving teams to avoid them and move the work to spreadsheets and one-off scripts.

It's also why I believe Orb has earned real expertise in pricing. Each of these lessons came from rebuilding a core part of the billing engine underneath companies that were already being billed, finding the scenario where the previous model broke, and fixing it without changing an invoice their customers had already received. That experience is what Orb customers get when they change their pricing in Orb.

Recapping

  • The billing engine tracks what each end customer pays, applies pricing changes, and turns usage and fees into invoices. Billing must be correct, and that's the bar for every change to it.
  • Two kinds of copies, child plans and the same price repeated across plans, added flexibility, and later iterations recorded what each copy was relative to. Child plans gave way to overrides recorded as differences, and repeated prices gave way to Pricebook's shared prices.
  • Every change is a difference applied to the subscription's timeline and tracks what it replaced, which is what lets overrides, migrations, and backdated changes work together safely.
  • Billing engine changes are gated by date, compared against the old code, and double-written, so that issued invoices stay as they were sent.

Based on my experience, my rule of thumb is this: whenever a billing engine copies a price to make room for one customer's exception, it should also record what it copied and what it changed. Whenever it needs the same price in another plan, it should reference that price instead of copying it. The copy is what gives you flexibility today. The record is what lets you answer, a year later, who pays what and why.

Related posts

Ready to try a billing platform built for modern growth?

See how AI companies are removing the friction from invoicing, billing and revenue.