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

# Organization Hierarchy

> Model corporate structures with parent-child relationships between customers.

Many organizations consist of a parent entity with multiple departments, locations, or subsidiaries. The organization hierarchy feature allows you to model these relationships directly in Fynn using a clear parent-child structure between customers.

<Info>
  The organization hierarchy requires the `customer.hierarchy` feature flag to be enabled. Contact support to activate this feature for your tenant.
</Info>

## Overview

With the organization hierarchy, you can:

* **Define parent-child relationships** between customers (e.g., headquarters → departments)
* **Model up to 3 hierarchy levels** (parent company → subsidiary → department)
* **View subscriptions, invoices, and transactions** filtered by organizational membership
* **Track hierarchy changes** through the activity trail

<Note>
  The organization hierarchy is a purely organizational feature. In the current version, it does not affect invoicing or payment processing. It serves as the foundation for upcoming features such as organization-based billing (consolidated billing).
</Note>

## Use Cases

| Industry   | Parent Customer            | Child Customers                      |
| ---------- | -------------------------- | ------------------------------------ |
| Healthcare | Klinik Musterstadt         | Radiology, Orthopedics, Cardiology   |
| Legal      | Schmidt & Partner Law Firm | Berlin Office, Munich Office         |
| Retail     | Retail Group GmbH          | Store North, Store South, Store West |

## Managing the Hierarchy

### Assign a Parent Customer

<Tabs>
  <Tab title="Using Web App">
    <Steps>
      <Step title="Open Customer Details">
        Navigate to the customer that should be assigned as a child to a parent customer.
      </Step>

      <Step title="Assign Parent Customer">
        In the Organization Hierarchy section, select and assign the parent customer.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Using API">
    Use the [Set parent customer](/api-reference/customer/set-parent-customer) endpoint.

    ```bash theme={null}
    PUT /customers/{customerId}/set-parent
    ```

    ```json theme={null}
    {
        "parentCustomerId": "00000000-0000-0000-0000-000000000000"
    }
    ```
  </Tab>
</Tabs>

### Remove a Parent Customer

<Tabs>
  <Tab title="Using Web App">
    <Steps>
      <Step title="Open Customer Details">
        Navigate to the child customer whose parent assignment should be removed.
      </Step>

      <Step title="Remove Parent Assignment">
        In the Organization Hierarchy section, remove the existing parent assignment. The customer becomes a standalone customer without hierarchy membership.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Using API">
    Use the [Remove parent customer](/api-reference/customer/remove-parent-customer) endpoint.

    ```bash theme={null}
    PUT /customers/{customerId}/remove-parent
    ```
  </Tab>
</Tabs>

### View Child Customers

<Tabs>
  <Tab title="Using Web App">
    On the customer detail page of a parent customer, the number of child customers is displayed. You can navigate directly to child customers from the Organization Hierarchy section.
  </Tab>

  <Tab title="Using API">
    Use the [Get customer children](/api-reference/customer/get-customer-children) endpoint to retrieve all direct child customers including metrics.

    ```bash theme={null}
    GET /customers/{customerId}/children
    ```

    The response includes customer data and the number of active subscriptions (`activeSubscriptionCount`) for each child customer.
  </Tab>
</Tabs>

### View the Full Hierarchy

Using the API, you can retrieve the complete hierarchy tree for any customer — regardless of whether you specify a parent or child customer. The response always starts from the root customer.

```bash theme={null}
GET /customers/{customerId}/hierarchy
```

```json theme={null}
{
    "root": {
        "id": "uuid-100",
        "name": "Klinik Musterstadt",
        "customerNumber": "CUST-100",
        "isCurrentCustomer": false,
        "children": [
            {
                "id": "uuid-101",
                "name": "Radiology",
                "customerNumber": "CUST-101",
                "isCurrentCustomer": true,
                "children": []
            },
            {
                "id": "uuid-102",
                "name": "Orthopedics",
                "customerNumber": "CUST-102",
                "isCurrentCustomer": false,
                "children": []
            }
        ]
    }
}
```

## Filtering the Customer List

The customer list supports additional filters for the organization hierarchy:

| Filter             | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `parentCustomerId` | Returns only direct child customers of the specified parent customer |
| `isParent=true`    | Returns only customers that have child customers                     |
| `hasParent=true`   | Returns only customers that are assigned to a parent customer        |

Example via the API:

```bash theme={null}
GET /customers?parentCustomerId={parentId}
GET /customers?isParent=true
GET /customers?hasParent=true
```

## Cross-Organization Views

When a parent customer is selected, subscriptions, invoices, and transactions of all associated child customers can be viewed together using the `parentCustomer` filter.

```bash theme={null}
GET /subscriptions?parentCustomer={parentCustomerId}
GET /invoices?parentCustomer={parentCustomerId}
GET /transactions?parentCustomer={parentCustomerId}
```

## Validation Rules

The following rules apply when managing the organization hierarchy:

| Rule                   | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| Maximum depth          | The hierarchy supports a maximum of 3 levels (root → child → grandchild) |
| No circular references | A customer cannot be its own parent, either directly or indirectly       |
| Same tenant            | Parent and child customers must belong to the same tenant                |
| Active parent          | The parent customer must not be archived                                 |
| Archive constraint     | A customer with active (non-archived) child customers cannot be archived |

## Webhooks

Changes to the organization hierarchy trigger webhook events:

| Event                      | Description                    |
| -------------------------- | ------------------------------ |
| `customer.parent.assigned` | A parent customer was assigned |
| `customer.parent.removed`  | A parent customer was removed  |

For more information on configuring webhooks, see [Webhooks](/en/guide/webhooks/introduction).

## Roadmap

The organization hierarchy is the foundation for upcoming organization-level billing features. Planned capabilities include:

* **Consolidated Billing:** Invoices for child customers can be directed to the parent customer.
* **Flexible Payment Routing:** Per child customer, configure who receives invoices and who is responsible for payment.
* **Consolidation Periods:** Invoices can be aggregated on a monthly or quarterly basis.