Overview
Customer families allow you to model hierarchical relationships between customers, such as a parent company and its subsidiaries, a headquarters and regional offices, or a holding entity and its portfolio companies.
A customer family consists of one parent customer and one or more child customers. This structure is a prerequisite for features like roll-up billing, where subscriptions belonging to child customers are invoiced to the parent.
Who This Is For
| Role | Involvement |
|---|
| Revenue Operations | Configures parent-child relationships during customer onboarding |
| Sales Operations | Establishes family structures when closing multi-entity deals |
| Finance | Processes consolidated invoices issued to parent customers |
| Support | Navigates family structures when troubleshooting billing questions |
How Customer Families Work
A customer family is a single-level hierarchy:
Parent Customer
├── Child Customer A
├── Child Customer B
└── Child Customer C
- A parent customer is any customer that has one or more children assigned to it. There is no explicit “make this a parent” action; a customer becomes a parent when another customer is assigned to it as a child.
- A child customer is any customer with a parent customer assigned. A child can have at most one parent.
- A standalone customer has no parent and no children.
There is no support for multi-level nesting. A parent customer cannot itself be a child of another customer.
Configuration & Usage
Creating a Child Customer
When creating a new customer, the Parent Customer (Optional) field allows you to assign a parent.
A parent-child customer relationship enables optional features, for example the ability to bill the parent for the child’s subscription(s).
- Navigate to Customers and click New Customer.
- Fill in the standard customer fields (name, email, address, etc.).
- In the Parent Customer (Optional) dropdown, select the desired parent.
- Save the customer.
Via the API:
Include the parentCustomerId field when creating a customer:
{
"name": "Acme West Coast",
"email": "billing@acme-west.com",
"parentCustomerId": "cust_abc123"
}
Changing or Removing a Parent
You can update or clear a customer’s parent at any time from the customer’s Profile page.
Via the Dashboard:
- Navigate to the child customer’s profile.
- In the Parent field, select a different parent or clear the selection.
- Save changes.
Via the API:
To change the parent:
{
"parentCustomerId": "cust_new_parent"
}
{
"clearParentCustomerID": true
}
Viewing Family Relationships
- A child customer’s profile displays its parent as a clickable link.
- A parent customer’s profile lists its children.
System Behavior & Guarantees
| Behavior | Detail |
|---|
| Maximum nesting depth | One level. A parent cannot be a child of another customer. |
| Parent eligibility | Only customers without a parent themselves can be selected as a parent. |
| Automatic billing updates | Changing a customer’s parent automatically recalculates billing schedules for the child, the old parent (if any), and the new parent (if any). |
| Parent deletion | Deleting a parent customer sets all children’s parent reference to null. Children are not deleted. |
| No automatic subscription changes | Changing a parent does not automatically enable or disable roll-up billing on existing subscriptions. Roll-up billing must be configured per subscription. |
Edge Cases & Special Scenarios
- Removing a parent from a child with active roll-up subscriptions: The system recalculates billing schedules. Future invoices will be billed directly to the (now standalone) customer instead of the former parent.
- Reassigning a child to a different parent: Billing schedules for the old parent, new parent, and the child are all recalculated automatically.
- Currency alignment: There is no system-enforced currency constraint between parent and child customers. However, roll-up billing requires subscriptions within a family to use the same currency for consolidated invoicing to work correctly.
Impact on Other Parts of Alguna
| Area | Impact |
|---|
| Roll-up billing | Customer families are a prerequisite. Roll-up billing cannot be enabled without a parent-child relationship. |
| Invoices | When roll-up billing is active, invoices for child subscriptions are billed to the parent. |
| Subscriptions | The roll-up billing toggle only appears on subscriptions belonging to child customers. |
| Customer portal | Each customer (parent or child) retains its own portal access. |
| Reporting | Subscriptions remain attributed to the serviced (child) customer for revenue reporting, even when billed to the parent. |
Examples
Enterprise with Regional Subsidiaries
Scenario: Acme Corp has three regional offices. Finance wants a single consolidated invoice.
| Customer | Role | Parent |
|---|
| Acme Corp | Parent | — |
| Acme EMEA | Child | Acme Corp |
| Acme APAC | Child | Acme Corp |
| Acme Americas | Child | Acme Corp |
FAQ
Can a customer be both a parent and a child?
No. Only one level of nesting is supported. A customer that already has a parent cannot be selected as a parent for another customer.
What happens to child customers if I delete the parent?
Child customers are not deleted. Their parent reference is cleared, making them standalone customers. Any roll-up billing on their subscriptions is recalculated.
Does assigning a parent automatically consolidate billing?
No. The parent-child relationship is a structural prerequisite. Roll-up billing must be explicitly enabled on each child subscription. See Roll-Up Billing.
Can I change a customer’s parent after subscriptions are active?
Yes. The system automatically recalculates billing schedules for all affected parties. Existing issued invoices are not modified; changes apply to future billing periods.
Is there a limit to how many children a parent can have?
There is no system-enforced limit on the number of child customers.
