Customer Families

Parent and child customers: the one-level hierarchy that makes roll-up billing possible

A customer family is a parent customer with one or more child customers: a holding company and its subsidiaries, a headquarters and its regional offices. Each child keeps its own subscriptions, contacts and portal access, but the family relationship is what allows a child’s subscriptions to be invoiced to the parent through roll-up billing. Set up a family when a group wants one consolidated invoice while usage and revenue stay attributed to the entity that consumed it. See Manage Customers for the customer record itself.

The parent relationship is set in the dashboard or through the public customer API, with parent_customer_id on POST /customers and PATCH /customers/{id}. See Set the parent through the API.

---

Who uses this

Role	Involvement
Revenue operations	Configures parent-child relationships during onboarding
Sales operations	Sets up the family when closing a multi-entity deal
Finance	Works with the consolidated invoices issued to the parent
Support	Navigates the family when answering billing questions

---

How families work

A customer family is a single-level hierarchy:

Parent Customer
├── Child Customer A
├── Child Customer B
└── Child Customer C

• A parent is any customer that has children. There is no explicit “make this a parent” action; a customer becomes a parent when another customer is assigned to it.
• A child has exactly one parent.
• A standalone customer has neither.

Nesting is one level deep: a parent cannot itself be a child.

---

Configuring a family

Assign a parent when creating a customer

1. Go to Customers and click New Customer.
2. Fill in the standard fields (name, email, address, currency).
3. In Parent Customer (Optional), select the parent. Only customers that do not already have a parent are offered, which prevents circular or multi-level hierarchies.
4. Save.

Change or remove a parent

Open the child customer’s profile, change or clear the Parent field, and save.

See the relationship

A child’s profile shows its parent as a link; a parent’s profile lists its children.

Set the parent through the API

The customer resource carries the relationship as parent_customer_id, the ID of the parent customer. It is returned on every customer that has a parent and omitted on every other customer.

Action	Request
Create a child	POST /customers with parent_customer_id
Assign or change the parent	PATCH /customers/{id} with parent_customer_id
Remove the parent	PATCH /customers/{id} with "clear_parent_customer_id": true. When it is true, parent_customer_id in the same request is ignored
List a parent’s children	GET /customers with the parent_customer_id query parameter

parent_customer_id accepts the same identifiers as the {id} in the request path: the parent’s Alguna customer ID, one of its aliases, or a connected-account external ID such as a Stripe customer ID. The response always returns the parent’s Alguna customer ID.

cURL

curl -X PATCH https://api.alguna.io/customers/$CHILD_CUSTOMER_ID \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d "{\"parent_customer_id\": \"$PARENT_CUSTOMER_ID\"}"

The API enforces the same one-level rule as the dashboard. A request is rejected with 400 when:

• the parent customer does not exist
• the parent customer is itself a child
• the customer would become its own parent
• the customer being updated already has children of its own

---

System behaviour

Behaviour	Detail
Maximum depth	One level. A parent cannot be a child of another customer
Parent eligibility	Only customers without a parent can be selected as a parent. A customer that has children cannot be given a parent
Billing schedules	Changing a customer’s parent recalculates billing schedules for the child, the old parent (if any) and the new parent (if any)
Deleting a parent	Clears the parent reference on every child. Children are not deleted
Roll-up is per subscription	Assigning a parent does not, by itself, change where anything is invoiced. Roll-up billing is enabled on each child subscription
Currency	No constraint is enforced between parent and child, but roll-up billing needs the subscriptions on one invoice to share a currency

Edge cases

• Removing a parent from a child with roll-up subscriptions: schedules are recalculated and future invoices go to the child directly. Issued invoices are not changed.
• Moving a child to a different parent: schedules for the old parent, the new parent and the child are all recalculated.

---

Impact elsewhere

Area	Effect
Roll-up billing	Requires a family. Cannot be enabled without a parent-child relationship
Invoices	With roll-up on, a child subscription’s charges are billed to the parent, grouped by subsidiary on the parent’s invoice
Customer portal	Each customer, parent or child, keeps its own portal access
Reporting and revenue	Subscriptions stay attributed to the serviced (child) customer, even when billed to the parent

---

Example

Acme Corp has three regional offices and finance wants a single invoice.

Customer	Role	Parent
Acme Corp	Parent	—
Acme EMEA	Child	Acme Corp
Acme APAC	Child	Acme Corp
Acme Americas	Child	Acme Corp

Each office has its own subscription. With roll-up billing enabled on each child subscription, Acme Corp receives one invoice with line items grouped by subsidiary, while usage, entitlements and revenue remain attributed to each office.

---

FAQ

Can a customer be both a parent and a child? No. Only one level is supported.

What happens to children if I delete the parent? They become standalone customers. Any roll-up billing on their subscriptions is recalculated.

Does assigning a parent consolidate billing automatically? No. The family is the prerequisite; enable roll-up billing per child subscription. See Roll-up billing.

Can I change a parent after subscriptions are active? Yes. Billing schedules for everyone affected are recalculated. Issued invoices are untouched; the change applies to future periods.

Is there a limit on children per parent? No system-enforced limit.