Core concepts

Orb’s query-based architecture is built on core entities that form your billing data model. This guide defines each entity, explains its role in the billing system, and links to relevant documentation for implementation.

​

Account

Every Orb resource lives within an Account. A single user of Orb (any person with access to the product) by default has access to two accounts, a live mode and a test mode. Note that other than sharing a user login, these environments are completely isolated, and you will need to use separate API credentials to access each account. In some cases, it’s possible to automatically copy objects between accounts to “promote” a configuration in test mode to live mode. The test mode account cannot be connected to a production payment processor, which prevents unintended money movement in non-production scenarios. The test mode account can still send emails to your users when triggered manually, in order to enable end to end testing of Orb. There are a few critical settings configured per account. In addition to those configurable on the account settings page directly, the following settings are configured during our onboarding process:

• Ingestion grace period: Determines how far the timestamp that an event is labeled with can lag the current wall time (usually 12 hours). As a side-effect, this is the minimum amount of time that Orb waits before issuing an end of period invoice that contains usage.
• Account logo: Determines the custom branding treatment for your invoices and end-user facing links.
• Timezone: Your account-wide timezone determines default billing behavior; see timezones for a more detailed discussion.

​

Customer

A Customer is a representation of a business or user that you sell to. Orb generally does not have personally identifying information about your customers, other than a name and email address. A Customer is the basis for all billing in Orb, and is the entity that has events, subscriptions, invoices, and payments associated with it.

​

Customer deletion: Test mode vs Live mode

Orb allows different customer deletion behaviors depending on whether you are operating in test mode or live mode: Test mode:

• Customers can be deleted even if they have issued invoices
• This provides flexibility for testing and development scenarios where you may need to clean up test data
• All associated subscriptions and invoices are also deleted as part of the customer deletion process

Live mode:

• Customers with issued invoices cannot be deleted to maintain data integrity and audit compliance
• This restriction helps ensure accurate financial records and prevents accidental loss of billing history
• Only customers without any issued invoices can be deleted in live mode

​

Event

An Event is a business-specific piece of data that you send to Orb. Depending on your business, the exact shape of your event stream may vary; events will form the basis of any usage-based prices that you charge your customers on. Events are meant to be the raw data that your application emits, rather than the change in a specific billable value; this gives you the flexibility to integrate your event stream once and evolve the metrics you construct over these events over time as requirements change. For example, if you’re tracking the number of monthly active users in your application, you should send Orb an event for each login (or perhaps even user activity) rather than the updated count of active users based your own aggregate summaries. Events are the foundation of Orb’s query-based architecture. Because events are stored immutably, metrics can be defined or changed at any time, and every charge is traceable to its source events—providing complete auditability.

​

Metric

A metric, also known as a “billable metric”, is a query over ingested events that outputs an aggregate value. This aggregate value (e.g. a COUNT or a SUM) can then be tied to a pricing model. Conceptually, think of a metric as a materialized view that Orb is responsible for keeping up to date for the relevant set of customers and billing periods; a metric doesn’t need to contain any customer or time specific context to operate. Metrics are queries, not pre-aggregated counters. This distinction is fundamental to Orb’s query-based architecture: metric definitions can be changed or applied to historical usage without re-ingesting data.

​

Item

An Item is a representation of what you sell. An Item does not necessarily represent a standalone sellable product; rather, it’s likely to be a component of a bundle that your business sells. Items are most directly used when tying data in Orb to a third-party. For example, Item mappings are used to tie to a tax treatment in tax automation software, or to sync line items to a different invoicing solution such as Stripe Invoicing or QuickBooks. Items are most often configured implicitly during the creation of other resources. For example, when you create a Metric, you must create or choose an existing Item. To manage your Items and their mappings, navigate to the Items page in the Orb webapp.

​

Plan and price

A Price is a representation of how much you charge for a given Item, where the usage is determined by a specific Metric. Each price has a specific “price model” (unit pricing, tiered pricing, etc.), which determines how the price is calculated from the aggregate value of the metric. A plan consists of one or more prices, and is often what you might consider your ‘list’ pricing. For example, if you see multiple tiers of your offering such as Pro, Starter, or Gold, each of these would correspond to a plan in Orb. Although a plan sets up default pricing for a given Item, it’s possible to override the pricing for a specific customer when creating a subscription.

​

Subscription

A subscription represents a customer’s recurring relationship with your business, and ties a Customer to a Plan in Orb. Depending on your business, a subscription may correspond to a specific service agreement or contractual commitment, or it may be the side-effect of your customer signing up to use your product.

​

Invoice

An invoice represents the charges that you’re passing on to your customer. Every active subscription in Orb generates invoices throughout its lifecycle, based on the cadence of prices (most commonly monthly). Unlike other billing products which only generate invoices at the end of a billing period, active subscriptions in Orb have an upcoming invoice that captures accrued usage charges. This is important because hybrid billing models don’t generate static invoices; in fact, the current period’s draft invoice is often the most important resource. Invoices consist of one or more line items, which are the individual component charges. Most invoices are generated by the subscription, and their line items correspond directly to the component prices on the Plan associated with the Subscription. Similar to other fully-featured invoicing products, invoices can be edited while in draft and may be associated with credit notes to represent invoice adjustments once they are issued. Orb is an invoicing product in addition to a billing product. Orb can deliver invoices to your customers via email, and features end-user facing invoice links to allow paying for an invoice via an integrated payment gateway such as Stripe. This functionality means that you can use Orb as a replacement for the Stripe Invoicing product if desired.

​

Object model diagram

The following diagram provides a visual reference of the core entities in Orb, and how they relate to each other. Note that this is a simplified diagram, and that some relationships aren’t fully detailed here.