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

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.

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.

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.

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.

In the Orb API, create a new subscriptionand 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.

Prices can also be duplicated to apply a different rate to a different group of customers for 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.

​

Modify a 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.

​

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.

Additionally, line items on an invoice will denote the billed customers

​

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.

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 need 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 use 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 the price intervals add or edit API to specify the customers to bill.