> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Families

> Organize customers into parent-child hierarchies to enable consolidated billing and account management

## 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](/invoices/rollup-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.

<Info>
  A parent-child customer relationship enables optional features, for example the ability to bill the parent for the child's subscription(s).
</Info>

Only customers that do not already have a parent are available for selection. This prevents circular or multi-level hierarchies.

**Via the Dashboard:**

1. Navigate to **Customers** and click **New Customer**.
2. Fill in the standard customer fields (name, email, address, etc.).
3. In the **Parent Customer (Optional)** dropdown, select the desired parent.
4. Save the customer.

**Via the API:**

Include the `parentCustomerId` field when creating a customer:

```json theme={null}
{
  "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:**

1. Navigate to the child customer's profile.
2. In the **Parent** field, select a different parent or clear the selection.
3. Save changes.

**Via the API:**

To change the parent:

```json theme={null}
{
  "parentCustomerId": "cust_new_parent"
}
```

To remove the parent:

```json theme={null}
{
  "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 |

Each regional office has its own subscription. With [roll-up billing](/invoices/rollup-billing) enabled on each child subscription, Acme Corp receives a single invoice containing line items grouped by subsidiary.

## 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](/invoices/rollup-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.