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