Skip to main content

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

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:
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.
This creates a new parent subscription and converts sub_analytics and sub_storage from standalone to grouped_invoicing type.Response (abbreviated):
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.
A child created with the parent through grouped_invoicing_children_to_create keeps the proration_behavior you send for it, and defaults to none when you omit it. To change a subscription’s proration_behavior later, send it on PUT /subscriptions/{id}. Omitting it leaves the stored value unchanged, and the change doesn’t rebill invoices that already exist.

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:

Option C: Remove a subscription from the group

On success, sub_compute reverts from grouped_invoicing back to standalone and its parent_subscription_id is cleared.

Post-creation changes

Use the modify API to add a subscription to an existing group or remove a subscription from the group. When a grouped contract’s parent belongs to a different customer, the child customer’s Invoices tab shows a notice linking to the parent customer. Open the parent customer’s Invoices tab to view the consolidated invoice. When both contracts belong to the same customer, the consolidated invoice appears under that customer.

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.

Credit notes and payments

A grouped invoice is one invoice with one balance. Each child’s line items carry the child’s subscription_id, so you can see which subscription a charge came from, but payments, refunds, and dunning apply to the invoice as a whole.

Payments

  • Payments apply to the whole invoice. A payment is never allocated to a specific subscription or line item. A customer cannot pay off one child’s charges while leaving another’s unpaid.
  • Partial payments keep the invoice pending. After a partial payment, amount_paid goes up, amount_remaining goes down, and payment_status stays PENDING until the invoice is paid in full.
  • Full payment is required before follow-up actions. Anything that waits for the invoice to be paid, such as activating a subscription, runs only when amount_remaining reaches zero.

Credit notes

Credit notes on a grouped invoice work line by line. To credit one subscription, reference that subscription’s line items in line_items:
The invoice’s payment_status decides the credit note type and how much you can credit: You also cannot credit more on a line item than that line was charged.
A partially paid invoice only accepts adjustments. While any balance is left, the invoice is PENDING, so a credit note can only reduce what is still owed. The amount already paid cannot be refunded until the invoice is paid in full. For example, on a $340 invoice with $100 paid, you can adjust up to $240 but refund nothing.
Refunds go to whoever paid the invoice. A refund credit note is settled against the payments made on the grouped invoice, even if you credited a single child’s line item. The money goes back to the parent subscription’s invoicing customer, not to the child’s customer. A refund of an offline payment is added to that customer’s prepaid wallet.

Example

A customer has a Pro subscription ($200) as the parent and a Startup subscription ($50) as a grouped child. With tax, the grouped invoice comes to $340.

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.
Two subscriptions created at different times on the same day have different billing anchors and cannot be grouped, even though they renew on the same date. To group them, pass the same billing_anchor when you create each subscription.
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 children are cancelled with the parent. When the parent’s cancellation takes effect, each active or trialing child is cancelled with the same end date and cancellation_reason, including payment_overdue when the parent was auto-cancelled for an unpaid invoice. The child’s line items, addons, future credit grants and commitments end on that date, its pending schedules are cancelled, and subscription.updated and subscription.cancelled webhooks are sent for it.On an immediate cancellation, the children’s final charges stay on the parent’s closing invoice. A proration credit covers only the parent’s line items. On an end_of_period or scheduled_date cancellation, the children stay active until the parent’s cancellation fires, so reverting the parent’s scheduled cancellation needs no change to the children.
The child stops immediately and leaves the group’s future invoices. It does not get a final invoice of its own. With proration_behavior set to create_prorations, the unused part of charges already billed in advance is credited to the customer’s prepaid wallet. The remaining children and the parent continue their normal billing cycle.
Yes. Create a credit note that references only that subscription’s line items. Payments are not tracked per subscription, though, so the refund is settled against the invoice’s payments and goes to the customer who paid the invoice.
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