In order to best use Orb, there are a few core data model concepts that are important to understand. This guide serves as a central resource to navigating these concepts, tying together both developer guides as well as specific API reference documentation to programatically manipulate these concepts.

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

​
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.
In addition to using Orb’s test mode for manual testing, consider integrating the test mode environment with your CI/CD pipeline for automated integration testing with 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.
Orb recommends setting the external_customer_id field on every Orb customer to a stable ID in your system, such as your customer’s primary key. This allows you to avoid denormalizing any Orb Customer IDs in your datastore, and makes both event reporting and resource management easier.

​
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
The test mode environment is completely isolated from live mode, so any customer deletion in test mode will not affect your production data or financial records.
ResourceDescription
Customer API referenceUsed to create, update, and fetch customers in Orb. If you have a self-serve business where users can sign up for service without your intervention, you should use this API to create a customer in Orb every time a user signs up.
Customer ID aliasesUse customer aliases for more ergonomic interaction with Orb’s customer APIs.

​
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.
ResourceDescription
Ingestion quickstartTakes you through some simple API commands so you can familiarize yourself with sending events to the API.
Ingestion guideThe developer guide includes examples of domain-specific events, how to determine your customized event schema, and the various ingestion integrations that Orb supports.
Batch ingestion APIA key part of any Orb integration, used to send events to the Orb platform. Orb is responsible for storing and appropriately indexing your event data.
Events backfill APIEvent backfills support overwriting previously ingested events in an audit-friendly way.

​
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.
ResourceDescription
Metrics quickstartWalks through the creation of some simple metrics, and is a useful starting point to understand filters available in the Orb webapp.
Metric creation guideLearn more about how to compose a metric, its component parts, and how custom metrics can be built via the flexibility of SQL.

​
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.
ResourceDescription
Configure pricing quickstartShows the creation of a new plan in the Orb webapp, to help familiarize you with the basics.
Product catalogDetails the different pricing levers that are available in the Orb webapp.
Plan API referenceUsed to fetch the pricing structure and any associated metadata for a specific plan.

​
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.
ResourceDescription
Subscription quickstartGuides you through the creation of a new subscription in Orb, and highlights important elements of the subscription lifecycle including your first set of invoices.
Subscription creationA detailed overview of the subscription lifecycle, and how core billing mechanics operate on Subscriptions.
Subscription modificationsA walkthrough of the ways to modify an existing subscription, including creating add-ons, changing pricing, and changing plans.
Subscription API referenceUsed to create subscriptions in Orb, including any overrides required to the pricing configuration of the base plan.
Subscription costs APIUsed to fetch accrued costs across a timeframe of the subscription. Integrate this API with your in-product billing portal to provide real-time transparency to your users.

​
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.
ResourceDescription
Invoicing quickstartSetting up and testing Orb’s invoicing product, including the metadata to customize your invoices for your business.
Invoicing guideA collection of guides to help you understand the key pieces of Invoicing functionality that Orb offers.
Invoice API referenceUsed to fetch an invoice by ID, or the upcoming invoice. Integrate this API to provide a detailed breakdown of charges to your customer.