Skip to main content

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.

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

IndustryParent CustomerChild Customers
HealthcareKlinik MusterstadtRadiology, Orthopedics, Cardiology
LegalSchmidt & Partner Law FirmBerlin Office, Munich Office
RetailRetail Group GmbHStore North, Store South, Store West

​
Managing the Hierarchy

​
Assign a Parent Customer

1

Open Customer Details

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

Assign Parent Customer

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

​
Remove a Parent Customer

1

Open Customer Details

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

Remove Parent Assignment

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

​
View Child Customers

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.

​
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:
FilterDescription
parentCustomerIdReturns only direct child customers of the specified parent customer
isParent=trueReturns only customers that have child customers
hasParent=trueReturns 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:
RuleDescription
Maximum depthThe hierarchy supports a maximum of 3 levels (root → child → grandchild)
No circular referencesA customer cannot be its own parent, either directly or indirectly
Same tenantParent and child customers must belong to the same tenant
Active parentThe parent customer must not be archived
Archive constraintA customer with active (non-archived) child customers cannot be archived

​
Webhooks

Changes to the organization hierarchy trigger webhook events:
EventDescription
customer.parent.assignedA parent customer was assigned
customer.parent.removedA 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.