Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Grouped invoicing lets a customer with multiple separate subscriptions receive a single invoice that combines all line items from every subscription in the group. Each subscription retains its own plan, line items, usage tracking, and entitlements. Only the invoice consolidation changes. subscription_type results:
  • Parent (invoice anchor): parent
  • Each grouped child subscription: grouped_invoicing
A standalone subscription acting as the parent is automatically promoted to parent type when the first child is added.

​
How it works

PropertyWhere it lives
Plan and line itemsEach child’s own subscription
Usage trackingEach child’s own subscription
EntitlementsEach child’s own subscription
InvoiceSingle consolidated invoice to the parent subscription’s customer
WalletParent subscription’s customer

​
When to use grouped invoicing

  • Multi-product company: A company uses analytics, storage, and compute as three separate Flexprice subscriptions. Finance wants a single monthly invoice instead of three.
  • Department consolidation: Different teams each have their own subscription. A central account manager wants one invoice per billing cycle.
  • Simplify payment: A customer manages multiple subscriptions independently but wants to reduce invoice processing overhead.

​
Prerequisites

Before adding a subscription to a grouped invoicing group, all of the following must be true:
RequirementWhat to check
Child subscription typeMust be standalone
Child subscription statusMust be active or trialing
Child has no existing parentparent_subscription_id must be null
Parent subscription typeMust be parent or standalone (auto-promoted on first child add)
Parent subscription statusMust be active or trialing
Billing periodChild and parent must have the same billing_period (for example both month)
Billing period countChild and parent must have the same billing_period_count (for example both 1)
Billing anchorChild and parent must share the same day-of-month and time-of-day billing anchor
CurrencyChild and parent must use the same currency
Start dateChild start_date must be on or after parent start_date
Flexprice validates all of these requirements before adding a subscription to a group. A single mismatch returns a validation error with a specific hint. Check the error’s hint field for which constraint failed.

​
Configure

​
Option A: Create a parent subscription and group existing subscriptions at creation time

Use this when you already have standalone subscriptions that you want to group under a new parent. 
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-acme-corp",
    "plan_id": "plan_base_monthly",
    "currency": "usd",
    "billing_period": "month",
    "billing_period_count": 1,
    "start_date": "2026-06-01T00:00:00Z",
    "inheritance": {
      "subscriptions_ids_for_grouped_invoicing": [
        "sub_analytics",
        "sub_storage"
      ]
    }
  }'
This creates a new parent subscription and converts sub_analytics and sub_storage from standalone to grouped_invoicing type.Response (abbreviated):
{
  "id": "sub_01parent",
  "subscription_type": "parent",
  "customer_id": "cus_acme",
  "status": "active"
}
At creation, subscriptions_ids_for_grouped_invoicing cannot be combined with external_customer_ids_to_inherit_subscription, invoicing_customer_external_id, or parent_subscription_id in the same request.

​
Option B: Add a subscription to an existing group

Use this when the parent already exists and you want to add more subscriptions to the group.
Preview before executing to confirm all constraints will pass:
curl -X POST https://api.flexprice.io/v1/subscriptions/{parent_subscription_id}/modify/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "grouped_invoicing",
    "grouped_invoicing_params": {
      "action": "add",
      "parent_subscription_id": "{parent_subscription_id}",
      "child_subscription_ids": ["sub_compute"]
    }
  }'

​
Option C: Remove a subscription from the group

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": "grouped_invoicing",
    "grouped_invoicing_params": {
      "action": "remove",
      "child_subscription_ids": ["sub_compute"]
    }
  }'
On success, sub_compute reverts from grouped_invoicing back to standalone and its parent_subscription_id is cleared.

​
Post-creation changes

Adding or removing group membership is done with the modify API (Option B and Option C above). There is no separate PATCH on the subscription resource for grouped invoicing membership beyond these flows.

​
Timing behavior

Adding a subscription to a group takes effect at the next billing period boundary. For the current period, any advance charges on the child have already been invoiced independently. Only usage accrued after the period rolls over appears on the consolidated parent invoice.
Removing a subscription from a group applies to the entire current billing period. The child’s invoice for the full current period (all usage and charges) is raised directly against the child customer’s subscription, regardless of when during the period the removal occurred.

​
Analytics

Each subscription in the group has its own usage tracking. Query each subscription owner’s external_customer_id individually. There is no include_children flag for grouped invoicing; that flag is for consolidated billing and inherited subscriptions only.

​
Validations and constraints

Billing period, billing period count, billing anchor, and currency must all match exactly. The billing anchor comparison uses the day-of-month plus time-of-day (hour:minute:second). Year and month are ignored, so a child added later in the year is accepted when its intra-cycle cadence aligns.
Cannot combine with consolidated billing at creation. subscriptions_ids_for_grouped_invoicing cannot be used in the same request as external_customer_ids_to_inherit_subscription, invoicing_customer_external_id, or parent_subscription_id.
Standalone parent auto-promotion. If the parent subscription is currently standalone, it is automatically promoted to parent type when the first child is added via the modify API. No manual type change is needed.

​
Frequently asked questions

Yes. Use POST /subscriptions/{id}/modify/preview with type: "grouped_invoicing" and action: "add". The preview validates constraints and returns what would change without making writes.
The cancelled child generates its own final invoice for the current period. The remaining children and the parent continue their normal billing cycle.
No. A subscription has one type. Grouped invoicing and consolidated billing use different mechanisms and cannot be mixed on the same parent subscription.

Consolidated Billing

When one parent plan should cover multiple customers

Delegated Invoicing

When a third party should receive the invoice for a standalone subscription