Orb has support for creating hierarchical relationships between your customers to power flexible pricing, usage aggregation, and invoicing. This capability is particularly valuable when your customers desire to aggregate usage across multiple customers on a single parent invoice while maintaining the ability to configure pricing per customer or groups of customers.
Customer hierarchy is not included with all Orb billing plans by default. Reach out to your Orb representative if you have any questions.
Customer hierarchy works in two parts:
  1. Create a hierarchy relationship between a parent and child customer(s)
  2. Configure pricing to use the hierarchy relationship

​
Create a hierarchy relationship

To get started, ensure your plan includes this feature. Browse to the settings page and enable the “Customer hierarchy” feature. Once Customer hierarchy is enabled, it cannot be disabled. enable-customer-hierarchy.png A hierarchy relationship can be created when creating a new customer or editing an existing customer.

​
Creating a customer as a parent

In the Orb UI, navigate to the customer creation page. Specify the child customers to include in the hierarchy for the newly created parent customer.
Create the child customers first before creating the parent customer, or create the parent customer first and then add the hierarchy relationships with child customers later.
Customers with existing hierarchy relationships cannot be added to another hierarchy.
customer-hierarchy-create-parent-customer.png In the Orb API, a hierarchy relationship can be created when creating a customer by setting the hierarchy field and specifying the child customers to include in the hierarchy. 
{
    "name": "Acme Corp",
    "email": "billing@acme.dev",
    "hierarchy": {
        "child_customer_ids": ["child_customer_id_1", "child_customer_id_2"]
    }
}

​
Creating a customer as a child

In the Orb UI, navigate to the customer creation page. Specify the parent customer to include in the hierarchy for the newly created child customer. customer-hierarchy-create-child-customer.png In the Orb API, a hierarchy relationship can be created when creating a customer by setting the hierarchy field and specifying the parent customer to include in the hierarchy. 
{
    "name": "Acme Legal",
    "email": "legal@acme.dev",
    "hierarchy": {
        "parent_customer_id": "parent_customer_id"
    }
}

​
Update a customer to be a child or parent

In the Orb UI, navigate to the customers page and select the customer you want to update. Scroll to the Customer details section to edit the customer. customer-hierarchy-edit-child-customer.png In the Orb API, a hierarchy relationship can be created when updating a customer by setting the hierarchy field and specifying either the parent customer or child customer(s) to include in the hierarchy.

​
Configure pricing to use a hierarchy relationship

With Customer hierarchy, you can now aggregate the usage of multiple customers on a single parent invoice. This enables the following billing configurations:
  1. Bill any mix of parent and child customers
  2. Bill child customers only
  3. Bill groups of child customers for different prices, with the same or different billable metric
With an existing hierarchy relationship, you can configure pricing to use the hierarchy relationship when creating a subscription or modifying the subscription price intervals.

​
Bill parent and child customers

In the Orb UI, create a new subscription and specify the parent and child customers to bill. customer-hierarchy-subscription-create.png In the Orb API, create a new subscription and specify the parent and child customers to bill. 
{
    "plan_id": "plan_id",
    "customer_id": "parent_customer_id",
    "start_date": "2025-01-01",
    "usage_customer_ids": ["parent_customer_id", "child_customer_id_1", "child_customer_id_2"]
}

​
Bill child customers only

In the Orb UI, create a new subscription and specify only the child customers to bill. In the Orb API, create a new subscription and specify only the child customers to bill. 
{
    "plan_id": "plan_id",
    "customer_id": "parent_customer_id",
    "start_date": "2025-01-01",
    "usage_customer_ids": ["child_customer_id_1", "child_customer_id_2"]
}

​
Specify customers to bill per price

A powerful feature of the hierarchy relationship is the ability to specify which customers will be billed individually or as part of a group for a given price. Toggle the Configure customers per price option to select specific customers from the hierarchy relationship for each price. customer-hierarchy-subscription-create-configure-customers.png Prices can also be duplicated to apply a different rate to a different group of customers for the same billable metric.
Duplicating a billable metric could lead to double billing of usage if the same customer is included in different price intervals with the same billable metric.
Below, a tiered price is used to rate the data storage usage for a group of customers in the hierarchy. That price is duplicated and modified to instead use a per-unit rate for another group of customers. customer-hierarchy-subscription-create-price-rates-duplicate.png In the Orb API, a existing price interval on a subscription can be modified, or a new price interval can be added, with the usage_customer_ids property set to specify the customers to bill. 
{
   "add": [
      {
         "start_date": "2025-01-01",
         "price_id": "price_id",
         "usage_customer_ids": [
            "child_customer_id_1",
            "child_customer_id_2"
         ]
      }
   ],
   "edit": [
      {
         "price_interval_id": "price_interval_id",
         "usage_customer_ids": [
            "parent_customer_id",
            "child_customer_id_2",
         ]
      }
   ]
}

​
Modify a hierarchy relationship

A hierarchy relationship that is in use in an active or upcoming subscription price cannot be modified. Cancel or end the subscription price before modifying the hierarchy relationship.
A hierarchy relationship can be modified by editing the customer. Note that a hierarchy relationship can only be modified if it is not in use in an active or upcoming subscription. customer-hierarchy-edit-active-subscriptions.png

​
Invoices

Customer hierarchy leads to usage aggregation at the parent customer level. This means that the usage for a subscription using a hierarchy relationship will be invoiced to the parent customer. In the Orb UI, on the customer details page for the parent customer, you can view the customer hierarchy table and the invoicing mode for each child customer. customer-hierarchy-invoicing-table.png Additionally, line items on an invoice will denote the billed customers customer-hierarchy-invoice-view.png In the Orb API, the usage_customer_ids property on an invoice line item will denote the billed customers.

​
Customer evaluation operations

There are several evaluation endpoints provided in the Orb API to build visualizations atop your event data and metrics. These operations can be used to evaluate prices, costs, and usage for a given customer or subscription. Here is a table summarizing the result of the evaluation operations based on the provided customer type in the hierarchy relationship.
OperationParent CustomerChild Customer
Evaluate priceThis will evaluate the price solely for the parent customerThis will evaluate the price solely for the child customer
Customer costsThis will aggregate costs across the hierarchy relationship in each subscriptionNothing will be returned for the child customer
Subscription costsThis will aggregate costs across the hierarchy relationshipNothing will be returned for the child customer
Subscription usageThis will aggregate usage across the hierarchy relationshipNothing will be returned for the child customer

​
Frequently Asked Questions

​
Can I create a hierarchy relationship between a parent and child in different currencies?

A hierarchy relationship can be created between a parent and child customers with different currencies. However since usage will be aggregated across the hierarchy and invoiced to the parent, only the currency of the parent will be used for the invoice.

​
Can I create a hierarchy relationship between a parent and child with different tax applications?

Similar to the differing currencies, since usage will be aggregated across the hierarchy and invoiced to the parent customer, only the tax application of the parent customer will be used for the invoice.

​
Will a newly created child customer inherit the subscription pricing from the parent customer?

The child customer will not inherit any existing subscription pricing from the parent customer. The prices on the parent customer’s subscription will need to be modified to include usage of the child customer. This can be done via the price intervals add or edit API

​
Does this feature support resellers and MSPs?

Customer hierarchy is not currently designed to support resellers and MSPs. For implementation guidance or support, reach out to your Orb representative.

​
How does this feature interact with deductions from a customer’s credit legder?

The ledger is scoped to a specific customer. Since invoicing for a subscription using a hierarchy relationship happens at the parent customer level, any usage (parent or child customers) will be deducted from the parent customer’s ledger. The ledger will show a single entry for usage deduction instead of a disaggregated breakdown per child customer. In other words, usage on a subscription linked solely to a child customer will drawdown only from the child customer’s ledger. However child customer usage on a parent customer subscription using a hierarchy relationship will drawdown from the parent customer’s ledger.

​
How does this feature interact with the subscription lifecycle?

​
Plan change

A subscription plan change ends the current price intervals on the subscription. As a result, for a subscription using a hierarchy relationship, any price interval usage customers configuration will be lost and needs to be re-configured.

​
Plan version and migration

Performing a subscription migration does not affect the hierarchy relationship on existing price intervals. New price intervals created as part of a migration will bill for usage of all customers in the hierarchy relationship.

​
How does this feature interact with manually triggered phases?

Customer hierarchy is not supported when creating a subscription with manually triggered phases. Manually trigged phases lead to the creation of new price intervals at the point of the trigger which can then be edited via usage_customer_ids property in the price intervals add or edit API to specify the customers to bill.