Organization Hierarchy

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.

The organization hierarchy requires the customer.hierarchy feature flag to be enabled. Contact support to activate this feature for your tenant.

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

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

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

Using Web App
Using API

Open Customer Details

Navigate to the customer that should be assigned as a child to a parent customer.

Assign Parent Customer

In the Organization Hierarchy section, select and assign the parent customer.

Use the Set parent customer endpoint.

PUT /customers/{customerId}/set-parent

{
    "parentCustomerId": "00000000-0000-0000-0000-000000000000"
}

Remove a Parent Customer

Using Web App
Using API

Open Customer Details

Navigate to the child customer whose parent assignment should be removed.

Remove Parent Assignment

In the Organization Hierarchy section, remove the existing parent assignment. The customer becomes a standalone customer without hierarchy membership.

Use the Remove parent customer endpoint.

PUT /customers/{customerId}/remove-parent

View Child Customers

Using Web App
Using API

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.

Use the Get customer children endpoint to retrieve all direct child customers including metrics.

GET /customers/{customerId}/children

The response includes customer data and the number of active subscriptions (activeSubscriptionCount) for each child customer.

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.

GET /customers/{customerId}/hierarchy

{
    "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:

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.

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.

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.

Getting Started

Customers

Products

Usage-Based Billing

Subscriptions

Invoices

Payments

Analytics

AI Assistant

Lists & Filters

Settings

Notifications

Accounting

Developers

Organization Hierarchy

Overview

Use Cases

Managing the Hierarchy

Assign a Parent Customer

Remove a Parent Customer

View Child Customers

View the Full Hierarchy

Filtering the Customer List

Cross-Organization Views

Validation Rules

Webhooks

Roadmap

​Overview

​Use Cases

​Managing the Hierarchy

​Assign a Parent Customer

​Remove a Parent Customer

​View Child Customers

​View the Full Hierarchy

​Filtering the Customer List

​Cross-Organization Views

​Validation Rules

​Webhooks

​Roadmap

Overview

Use Cases

Managing the Hierarchy

Assign a Parent Customer

Remove a Parent Customer

View Child Customers

View the Full Hierarchy

Filtering the Customer List

Cross-Organization Views

Validation Rules

Webhooks

Roadmap