Skip to main content
Customer Hierarchy is an enterprise-grade feature that enables you to establish parent-child relationships between customers for consolidated billing and flexible organizational structures. This powerful capability allows you to aggregate usage across multiple entities while maintaining separate subscription ownership and entitlements.

​
Overview

Customer Hierarchy allows you to decouple who uses the service from who pays for it. This is essential for enterprises with multiple business units, reseller partnerships, or complex organizational structures that require centralized billing while maintaining granular usage tracking.

​
Key Benefits

  • Consolidated Invoicing: Roll up charges from multiple child customers onto a single parent invoice
  • Flexible Pricing: Apply different pricing configurations across business units while maintaining unified billing
  • Usage Aggregation: Track usage at the entity level while billing at the parent level
  • Simplified Procurement: Streamline vendor management with a single billing relationship
  • Organizational Flexibility: Support complex corporate structures, reseller models, and multi-entity operations

​
How It Works

​
Parent-Child Relationships

In Flexprice, you establish a customer hierarchy by specifying an invoicing_customer_id when creating a subscription. This creates a clear separation between:
  • Subscription Owner (Child): The customer entity that owns and uses the subscription
  • Invoicing Customer (Parent): The customer entity that receives invoices and handles payment

​
Creating a Hierarchical Subscription

When creating a subscription, specify the invoicing_customer_id to designate which customer should be billed: 
POST /subscriptions
{
  "customer_id": "cus_subsidiary_123",
  "plan_id": "plan_enterprise",
  "invoicing_customer_id": "cus_parent_corp_456",
  "currency": "usd",
  "billing_period": "month",
  "billing_period_count": 1
}
What happens:
  1. The subscription is owned by cus_subsidiary_123 (the child entity)
  2. All invoices are generated for cus_parent_corp_456 (the parent entity)
  3. Usage is tracked under the subsidiary but billed to the parent
  4. Payment methods and wallets from the parent customer are used for settlement
Multiple Subscriptions: You can create multiple subscriptions for different child customers, all invoiced to the same parent customer. This allows you to aggregate usage and charges from multiple entities onto a single parent invoice while maintaining separate subscription management for each child customer.

​
Invoice Generation & Billing

When invoices are generated:
  1. Flexprice checks for the invoicing_customer_id on each subscription
  2. Invoices are created with the parent customer as the billing entity
  3. All charges appear in the parent customer’s billing history
  4. Payment processing uses the parent customer’s payment methods and wallet balance
  5. Invoice line items reflect the source subscription owned by the child customer
This ensures complete separation between service consumption and financial responsibility. The child customer’s usage is tracked and attributed correctly, while all financial operations (invoicing, payment, wallet deductions) occur at the parent customer level.

​
Use Cases

​
Enterprise with Multiple Subsidiaries

A global corporation with regional subsidiaries needs centralized billing while maintaining separate usage tracking for each business unit. Setup:
  • Parent: Global Corporation HQ
  • Children: Regional subsidiaries (APAC, EMEA, Americas)
  • Benefit: Each subsidiary has its own subscription and usage tracking, but HQ receives a single consolidated invoice

​
Reseller & Partner Models

A channel partner resells your software to their clients and handles billing to end customers separately. Setup:
  • Parent: Reseller/Partner
  • Children: End customer organizations
  • Benefit: Reseller receives all invoices and manages payment, while end customers maintain their own subscriptions and usage

​
Multi-Brand Organizations

A holding company operates multiple brands, each with their own customer identity but centralized finance operations. Setup:
  • Parent: Holding Company Finance Department
  • Children: Individual brand entities
  • Benefit: Brands operate independently with their own subscriptions, but finance handles all vendor payments centrally

​
Departmental Billing

Large organizations with multiple departments where a central finance or IT department manages vendor relationships. Setup:
  • Parent: Finance or IT Department
  • Children: Engineering, Marketing, Sales teams
  • Benefit: Teams use services independently, but billing is centralized for budget management

​
Payment & Wallet Behavior

Since invoices are assigned to the parent (invoicing customer), all payment operations use the parent’s financial resources:
  • Wallet Credits: Parent customer’s prepaid or promotional wallet balance is applied to invoices
  • Payment Methods: Saved cards and payment gateway configurations from the parent customer are used
  • Payment History: All transactions appear in the parent customer’s payment records

​
Wallet and Ledger Deductions

The wallet and credit ledger are scoped to a specific customer. Since invoicing for a subscription using customer hierarchy happens at the parent customer level, all usage (from the child customer’s subscription) will be deducted from the parent customer’s wallet or ledger balance. The ledger will show entries for usage deductions from the parent customer, reflecting the aggregated charges from child customer subscriptions.

​
Invoices

Customer hierarchy leads to usage aggregation at the parent customer level. This means that all invoices for subscriptions using an invoicing_customer_id will be generated for the parent (invoicing) customer.

​
Invoice Line Items

Invoice line items will reflect charges from the child customer’s subscription, but the invoice itself will be assigned to the parent customer. This allows you to see which subscriptions and usage contributed to the invoice while maintaining consolidated billing.

​
Viewing Invoices

  • All invoices appear in the parent customer’s billing history
  • Invoice line items show the source subscription and usage details
  • Payment processing and wallet deductions occur at the parent customer level

​
Frequently Asked Questions

​
Can I create a hierarchy relationship between a parent and child in different currencies?

A subscription can be created with a child customer in one currency and an invoicing customer (parent) in a different currency. However, since usage will be aggregated and invoiced to the parent customer, only the currency of the parent (invoicing) customer will be used for the invoice.

​
Can I create a hierarchy relationship between a parent and child with different tax applications?

Similar to differing currencies, since usage will be aggregated and invoiced to the parent customer, only the tax application of the parent (invoicing) customer will be used for the invoice.

​
Will a newly created subscription with an invoicing_customer_id inherit pricing from the parent customer?

No. The subscription is owned by the child customer and uses the plan and pricing associated with that subscription. The invoicing_customer_id only determines which customer receives the invoice and handles payment.

​
How does this feature interact with deductions from a customer’s wallet or ledger?

The wallet and credit ledger are scoped to a specific customer. Since invoicing for a subscription using customer hierarchy happens at the parent customer level, all usage from the child customer’s subscription will be deducted from the parent customer’s wallet or ledger balance. In other words, usage on a subscription owned by a child customer but invoiced to a parent customer will drawdown from the parent customer’s wallet/ledger, not the child customer’s.

​
How does this feature interact with the subscription lifecycle?

​
Plan Changes

When you change a subscription’s plan, the invoicing_customer_id relationship is preserved. The subscription continues to be owned by the child customer but invoiced to the parent customer.

​
Subscription Cancellation

If you cancel a subscription that uses customer hierarchy, the final invoice will be generated for the parent (invoicing) customer, and any remaining charges will be billed accordingly.