Organizing customers into a hierarchy lets you represent a company with multiple offices and keep their billing-related activity separate. Shared service configuration (e.g., extensions and hunt groups) can be set up once and reused across the hierarchy.
A customer hierarchy includes two customer types:
- Main Office (HQ) – the main customer in the hierarchy. Shared services are configured for this customer. Extensions and hunt groups created for the Main Office become available to all linked customers.
- Branch Office – a subordinate customer created under the Main Office. This customer has access to the Main Office extensions and hunt groups.
In the CloudPBX Self-Care Portal (available via the Add-on Mart) or a custom portal built with the PortaBilling API:
- Branch office customers can view, add, update, and delete their own extensions, but cannot manage hunt groups.
- Main Office customers can manage both extensions and hunt groups.
A customer hierarchy is also useful for companies with geographically distributed offices. Each office can be configured as a separate customer in the hierarchy to keep billing statistics and invoicing separate for each location.
ABC company has a main office onshore and several offshore oil rigs. Rig staff need to call the main office using extensions and access the main office hunt groups. At the same time, the accounting team requires billing and payments to be tracked separately for each rig.
An administrator creates the ABC company Main Office (HQ) customer in PortaBilling and configures extensions and hunt groups for it. The administrator then creates multiple Branch Office customers (one per rig) and links them to the Main Office (HQ). Because extensions and hunt groups configured for the Main Office (HQ) are available to linked Branch Office customers, no additional configuration is required for each branch.
The administrator then configures billing settings, such as invoice generation and balance management, for each Branch Office customer so that billing statistics are tracked separately for each rig.
Configuration
To configure the customer hierarchy, first enable this feature for the Main Office (HQ) customer:
- Go to the Customer > General info > Additional info tab.
- Turn on the Use the hierarchy of offices toggle.
- For the Office option, leave Main (HQ).
Then enable Use the hierarchy of offices for each subordinate customer, set the customer type to Branch, and link the customer to the appropriate Main Office.
See the details in the How to configure the customer hierarchy section.
Consolidated invoice for customer hierarchy
Consolidated invoicing combines charges from all offices in a customer hierarchy into a single invoice issued to the Main Office (HQ) customer.
To set this up, an administrator:
- Creates the ABC company Main Office (HQ) customer and multiple Branch Office customers with the same billing period, and links them in a hierarchy.
- For the Main Office (HQ) customer:
- enables invoice generation
- enables statistics generation
- configures taxation settings
To avoid discrepancies during tax calculation, disable tax calculation for all Branch Office customers in the group.
For the Main Office (HQ) customer, do not use consolidated invoicing with external taxation plug-ins such as SureTax. These plug-ins currently have no tax code for consolidated charges, so correct taxes cannot be applied. This limitation does not affect the VAT plug-in, which applies tax to the total amount without requiring service-level codes.
At the end of the billing period, the system generates a consolidated invoice for the Main Office (HQ) customer. The invoice includes the total charged amount for all offices in the hierarchy.
The system generates consolidated invoices according to the time zone defined for the Main Office (HQ) customer. If branch offices are located in different time zones, you may need to postpone invoice generation until their billing periods are closed. In this case, use the customer class option Close the billing period.
To generate an individual invoice for a branch office, disable the Include charges in the invoice to the main office option for the corresponding Branch Office customer.
The Main Office (HQ) customer can also receive xDRs in a CSV file for each branch office. For that, an administrator:
- Enables the Send_Stats_If_No_Invoice option on the Configuration server.
- Enables the Send the generated .csv files via email option for all Branch Office customers in the group.
- Sets the Main Office (HQ) customer email as the main contact email for all Branch Office customers in the group.
Interconnection between status of the Main Office and the Branch Office customers
Before generating a consolidated invoice, PortaBilling checks the status of the Main Office (HQ) customer. The Main Office status determines both service availability for Branch Office customers and whether a consolidated invoice is generated.
If the Main Office status is Active, Blocked, Suspended/Service limited, or Provisionally terminated, Branch Office services remain available until each office's credit limit or spending plan is reached. A consolidated invoice is generated for all these statuses, except for Provisionally terminated – in this case, no invoice is generated, and Branch Office charges are not added to the Main Office balance.
If the Main Office status is Permanently terminated, no services are provided, and no invoices are generated.
