Consolidated Billing

Overview

Consolidated billing lets an enterprise or holding company purchase one plan that covers multiple subsidiary teams or entities. Each child customer generates usage independently, but all usage aggregates under the parent subscription, producing a single invoice for the parent. subscription_type results:

Parent subscription: parent
Each child: inherited (auto-created skeleton, no line items)

How it works

Property	Where it lives
Plan and line items	Parent subscription
Usage tracking (billing)	Parent subscription (rolled up from all children)
Usage tracking (analytics)	Per child customer (use `include_children` to aggregate)
Invoice	Parent customer only
Wallet	Parent customer
Entitlements	Parent subscription
Child subscriptions	Skeleton only: no line items, no independent invoice

When to use consolidated billing

Enterprise with subsidiaries: Global HQ purchases an enterprise plan. Regional divisions (APAC, EMEA, Americas) each generate usage independently. HQ receives one consolidated invoice.
Holding company: A holding company owns multiple brands. Each brand operates as a customer. Finance at HQ handles all invoices.
Internal chargeback: A company tracks usage per department for internal reporting, but the central IT team is invoiced.

Prerequisites

Parent customer created in Flexprice
Each child customer created in Flexprice (with a known external_id)
A plan created in the product catalogue
Child customers must not already have an active inherited subscription under another parent

On create, you cannot combine inheritance.external_customer_ids_to_inherit_subscription with invoicing_customer_external_id or subscriptions_ids_for_grouped_invoicing in the same request.

Configure

Step 1: Create customers

Create the parent customer and each child customer through the Dashboard or API. Customer records have no hierarchy fields; they stay flat.

Step 2: Create the parent subscription with child inheritance

Dashboard
API

Navigate to Subscriptions and click Create Subscription
Select the parent customer and choose a plan
In the Customer Hierarchy section, enter the external IDs of the child customers who will inherit this subscription
Click Create Subscription

curl -X POST https://api.flexprice.io/v1/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "ext-global-hq",
    "plan_id": "plan_enterprise_monthly",
    "currency": "usd",
    "billing_period": "month",
    "billing_period_count": 1,
    "start_date": "2026-06-01T00:00:00Z",
    "inheritance": {
      "external_customer_ids_to_inherit_subscription": [
        "ext-apac-team",
        "ext-emea-team"
      ]
    }
  }'

Response (abbreviated):

{
  "id": "sub_01parent",
  "subscription_type": "parent",
  "customer_id": "cus_hq",
  "status": "active"
}

Flexprice automatically creates an inherited skeleton subscription for each child external ID. Verify by calling GET /subscriptions filtered by the child customer.

Step 3: Verify

Open the parent subscription’s detail page. Child skeleton subscriptions appear under it.

Post-creation changes

You can add additional child customers to an existing parent subscription using the modify API.

curl -X POST https://api.flexprice.io/v1/subscriptions/{parent_subscription_id}/modify/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inheritance",
    "inheritance_params": {
      "external_customer_ids_to_inherit_subscription": ["ext-latam-team"]
    }
  }'

Replace {parent_subscription_id} with the id of the parent subscription.You can preview the modify operation without committing changes using POST /subscriptions/{id}/modify/preview with the same request body.

Analytics: per-child and aggregated

Inherited children do not appear in billing usage summaries. All billable usage is attributed to the parent subscription. For analytics (non-billing), use POST /events/analytics. Aggregate all children under the parent:

curl -X POST https://api.flexprice.io/v1/events/analytics \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "ext-global-hq",
    "start_time": "2026-06-01T00:00:00Z",
    "end_time": "2026-06-30T23:59:59Z",
    "include_children": true
  }'

Per-child usage breakdown:

curl -X POST https://api.flexprice.io/v1/events/analytics \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "ext-apac-team",
    "start_time": "2026-06-01T00:00:00Z",
    "end_time": "2026-06-30T23:59:59Z"
  }'

include_children: true aggregates all inherited children’s usage into the parent’s response. Query each child’s external_customer_id individually to see per-child contribution.

Get customer usage summary for a child that only has an inherited subscription returns no billable usage on that child. This is expected. Confirm totals on the parent customer or use analytics as above.

Validations and constraints

Child already has an inherited subscription. A customer that already has an inherited subscription under another parent cannot be added as a child here. Error: "customer already has an inherited subscription". Resolve: cancel the existing inherited subscription or use a different child customer.

Inherited subscriptions cannot be cancelled directly. Calling cancel on an inherited subscription returns an error: "inherited subscription cannot be cancelled directly". Cancel the parent subscription instead. All inherited children are cancelled automatically at the same time.

Cascade behavior. When the parent subscription is paused, resumed, or cancelled, all inherited children are updated to match automatically.

Wallet balance. The parent customer’s wallet is used for all settlement. Inherited children have no independent wallet balance for this subscription.

Mutual exclusion. The inheritance.external_customer_ids_to_inherit_subscription field cannot be combined with invoicing_customer_external_id or subscriptions_ids_for_grouped_invoicing in the same request.

Frequently asked questions

Can parent and child subscriptions use different currencies?

No. Currency is set on the parent subscription and applies to all invoices. Inherited children use the parent’s currency.

What happens to inherited subscriptions when the parent is upgraded?

Plan changes apply to the parent subscription only. Inherited skeleton subscriptions keep routing usage events to the updated parent.

Why does getCustomerUsageSummary return zero usage for my child customer?

Billable usage for inherited subscriptions is attributed to the parent subscription. A child with only an inherited subscription has no independent billing usage ledger. This is expected. Use POST /events/analytics for per-child breakdowns.

Delegated Invoicing

When children need their own subscriptions but a third party pays

Grouped Invoicing

When separate subscriptions should merge into one invoice

Introduction

Getting Started

Connect

Event Ingestion

Product Catalogue

Customers

Subscriptions

Wallet

Invoices

Webhooks

Settings

Collectors

Data Exports

RBAC

Cookbooks

Contributing Guide

Consolidated Billing

Overview

How it works

When to use consolidated billing

Prerequisites

Configure

Step 1: Create customers

Step 2: Create the parent subscription with child inheritance

Step 3: Verify

Post-creation changes

Analytics: per-child and aggregated

Validations and constraints

Frequently asked questions

Delegated Invoicing

Grouped Invoicing

Introduction

Getting Started

Connect

Event Ingestion

Product Catalogue

Customers

Subscriptions

Wallet

Invoices

Webhooks

Settings

Collectors

Data Exports

RBAC

Cookbooks

Contributing Guide

Documentation Index

​Overview

​How it works

​When to use consolidated billing

​Prerequisites

​Configure

​Step 1: Create customers

​Step 2: Create the parent subscription with child inheritance

​Step 3: Verify

​Post-creation changes

​Analytics: per-child and aggregated

​Validations and constraints

​Frequently asked questions

​Related workflows

Delegated Invoicing

Grouped Invoicing

Overview

How it works

When to use consolidated billing

Prerequisites

Configure

Step 1: Create customers

Step 2: Create the parent subscription with child inheritance

Step 3: Verify

Post-creation changes

Analytics: per-child and aggregated

Validations and constraints

Frequently asked questions

Related workflows