Multi-entity billing lets one Orb account bill from several legal companies. We built it into Orb's foundational models rather than on top of them, so any account can turn it on and keep its existing setup, and a short inheritance chain routes every subscription to exactly one seller.
Every invoice names a seller: the legal company that is owed the money, its address, and the tax IDs it is registered under. Throughout this post, an Orb customer is the business that uses Orb to bill, and an end customer is the business or person that receives the invoice. For most of Orb's history, the seller on an Orb customer's invoices was the Orb account itself – one company name, one address, and one list of tax IDs, printed on every invoice the account issued.
This works until an Orb customer sells through more than one legal company. A business that grows from the US into the UK and the EU frequently does so through subsidiaries, and each subsidiary has to invoice under its own name, show its own tax registrations, and collect into its own payment account. With one seller per account, the options were a separate Orb account per subsidiary (with plans and metrics duplicated across them) or invoices that didn't name the right company.
Multi-entity billing solves this inside one account. An entity is one of an Orb customer's legally registered sellers, and an account can hold as many as it needs. Three choices make entities configurable without making them difficult to set up:
- The entity is a basic part of Orb's data model rather than a few fields on the invoice, so every subscription, invoice, credit note, and payment reads the seller from the same place.
- Entity details are versioned, so an entity can be edited at any time without changing invoices that were already sent.
- A short inheritance chain chooses the entity, so most setups take a default or two rather than a decision on every subscription.
One seller per account
Consider Acme Corporation, a US company that bills its end customers for LLM tokens through Orb. Acme opens Acme UK Ltd. to sell to British end customers, and Acme UK Ltd. registers for VAT. Acme's next British end customer should receive an invoice from Acme UK Ltd., with Acme UK Ltd.'s London address and VAT number, paid into Acme UK Ltd.'s Stripe account.
Where does that VAT number go? When the seller is the account, the account has a single company name, address, and tax ID list. Adding the VAT number to the account prints it on every invoice, including the invoices Acme Corporation sends to its US end customers. Leaving it off means the British invoice names the wrong company.
The usual answer was a second Orb account for Acme UK Ltd. This kept each company's invoices correct, but it split one business in two: the same plans and metrics had to be maintained in both accounts, and an end customer that moved between companies had to be recreated. None of this is a pricing problem. Acme sells the same product at the same prices, and only the seller changes.
The entity in the data model
Each entity stores a company name, an address, its tax IDs (a VAT number in the UK, an EIN in the US), a default memo, and the payment accounts that can collect its invoices: Stripe accounts, Adyen merchant accounts, or both, one of which is the entity's default. Every account has exactly one default entity.
The quicker path would have been a few seller fields on the invoice, and every feature that cares about the seller (the tax IDs printed, the memo, the tax registrations that apply, the payment account to charge) would then need an answer of its own. Instead, we added the entity to the foundational models those features already read. Customers, plans, subscriptions, invoices, credit notes, tax registrations, payment accounts, and each customer's link to a payment account all carry the same reference to an entity, with the same rule for records that don't have one yet.
Customers (Orb's record of each end customer), items, prices, and plans stay shared across entities, so Acme keeps a single catalog. Each subscription and one-off invoice belongs to exactly one entity, a credit note uses the entity of the invoice it applies to, and a customer or a plan can optionally name a default entity. As Fig 1 shows, every feature reads the seller from that one place, so none of them can disagree.

Every invoice has exactly one seller. Subscriptions and invoices created before an account added entities have no entity of their own, and Orb treats them as belonging to whichever entity is currently the account's default. The default entity can't be archived, and neither can an entity that customers, active plans, or active or upcoming subscriptions still use, so the customers, plans, and subscriptions in use always point at an active seller.
The inheritance chain
Orb chooses a new subscription's entity by walking a short chain, shown in Fig 2. An entity named in the request wins. Otherwise Orb uses the customer's default entity, then the plan's default entity, and finally the account's default entity. A one-off invoice follows the same chain without the plan step.

Every link except the last is optional, because the account's default entity always answers. Acme sets a default where one rule covers many subscriptions (every British end customer buys from Acme UK Ltd.) and names an entity on a request only for the exception. A plan's default is a fallback rather than a restriction, so the request or the customer's default can still name another entity.
The chain runs once, when the subscription is created. Every invoice the subscription produces uses that entity, and a later change to a customer's or a plan's default only affects new subscriptions. To move an end customer to a different entity, Acme ends the subscription and creates a new one, so each subscription the chain assigns keeps one seller for the whole contract.
Versions
Entities change. A subsidiary moves offices, registers for tax in a new country, or corrects its legal name. Each change to an entity's name, address, or tax IDs creates a new version, and earlier versions are never modified. A draft invoice always shows the entity's current version. When an invoice is issued, it records the version that was current at that moment, and its seller details come from that version from then on. Regenerating an issued invoice pulls the current version again, so a correction can be applied to an invoice on purpose.
Concretely, suppose Acme UK Ltd. moves from Manchester to London on March 1st. As Fig 3 shows, the January invoice was issued on February 1st and keeps the Manchester address. The March invoice is a draft on March 1st, so it picks up the London address and keeps it when it is issued on April 1st.

Credit notes follow the same rule and use the seller details of the invoice they apply to. Versioning is also what makes an entity safe to edit at any time: drafts pick up the change, and invoices the end customer has already received don't.
Payments across providers
Orb accounts could already connect both Stripe and Adyen and choose a provider for each end customer. Multi-entity billing adds two things. An Orb account can now connect several Stripe accounts, and its single Adyen connection, made at the level of one Adyen company account, makes every active merchant account in that company available, including ones added later. Each entity then lists the Stripe accounts, Adyen merchant accounts, or both that can collect its invoices, and marks one of them as its default.
Because payment accounts are attached to entities rather than to the Orb account, each company collects through its own provider and accounts. Acme Corporation and Acme UK Ltd. can each use a separate Stripe account while Acme Europe B.V. uses Adyen merchant accounts, all within one Orb account.
Orb picks the payment account for an invoice with a second short chain, which starts from the entity the first chain chose:
- The payment account the customer uses with the invoice's entity, if one is set.
- Otherwise, the entity's default payment account.
A customer can use a different payment account with each entity. Orb sets it when the customer is first connected to a payment account on that entity, and it can be changed in the customer's payment settings. In Fig 4, which uses the setup from the worked example below, Brightline Ltd. pays Acme Europe B.V. through the Adyen merchant account it uses with that entity rather than through Acme Europe B.V.'s default. Saved payment methods belong to an entity's payment account, so a card saved for Acme UK Ltd.'s Stripe account is charged only for Acme UK Ltd.'s invoices. With Adyen, payments that don't belong to an invoice, such as buying credits, go through the default entity's default payment account.

Events come back the same way. Adyen sends events from every merchant account in an Adyen company account to a single Orb webhook, and Orb routes each event to the right entity by its merchant account, ignoring merchant accounts that aren't attached to an entity. A payment account can't be removed from an entity while a payment through it is still in progress.
Changing providers for one company means changing that entity's payment accounts, without touching plans, subscriptions, or the other companies. End customers may need to save a payment method again, since saved methods belong to the account they were saved on.
Turning it on
Any existing account can turn on multi-entity billing, and its setup keeps working as it did. The account's default entity is created from the company details it already has: its company name, address, memo, and tax IDs. Every customer, plan, subscription, invoice, and payment account created before then has no entity of its own, so it belongs to the default entity, and every request can keep leaving the entity out. As Fig 5 shows, invoices look the same as before, payments go through the same accounts, and there is no migration work for the customer.

For an Orb customer with one company, that is the whole setup. Configuration starts with the second entity, and only for the customers, plans, and payment accounts that need it.
For an Orb customer with several companies, the same chain covers setups that look very different. Each of the following runs from one account and one catalog.

No setup in the table asks the Orb customer to copy a plan, recreate a customer, or move data between accounts.
A worked example
The following scenario shows the inheritance chain and payment routing working together in one account. Acme Corporation has three entities: Acme Corporation (the default entity), Acme UK Ltd., and Acme Europe B.V. Acme sells a Starter Plan with no default entity and an EU Enterprise Plan whose default entity is Acme Europe B.V. Acme Corporation and Acme UK Ltd. each collect through their own Stripe account, and Acme Europe B.V. collects through Adyen merchant accounts, one of which is its default.

Widgets Inc. has no default entity and neither does its plan, so the account's default entity sells to it. Brightline Ltd.'s default of Acme UK Ltd. is enough on its own. Kestrel GmbH has no default, so the plan decides. Fjord AS's plan points at Acme Europe B.V., but the customer's default points at Acme UK Ltd., and the customer is checked before the plan. If Acme wants Acme Europe B.V. to sell to Fjord AS, it names Acme Europe B.V. when creating the subscription.
Later, Brightline Ltd. signs a contract for the EU. Acme creates a second subscription to the EU Enterprise Plan and names Acme Europe B.V. when creating it, so the same customer record now holds one subscription from each company, each invoiced by its own seller and charged through that seller's payment account, as in Fig 4.
What we learned
Build the concept into the foundational models, and give existing data a home. Invoice headers, tax IDs, memos, credit notes, and payment collection each need to know who the seller is. Answering it in one place keeps them from disagreeing, and treating existing records as belonging to the default entity lets any account adopt entities without migration work.
Put flexibility in defaults, and strictness in the rules. The account, the customer, the plan, and the request can each choose an entity, so a new setup is usually a few settings. After the choice, each invoice has one seller, and a subscription keeps the entity the chain chose for it.
Version what end customers have already received. Issued invoices keep the version they were issued with, which is what lets an entity be edited at any time.
Rule of thumb
Based on my experience, my rule of thumb is that when several features each need the same fact, that fact belongs in the data model once, with a rule for how it is chosen and a rule for when it stops changing. Multi-entity billing follows that rule for the seller, which is what allows an Orb customer to go from one legal company to several in the same account, with the same catalog and the same customers.

