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: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.- API
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.- API (preview first)
- API (execute)
Preview before executing to confirm all constraints will pass:
Option C: Remove a subscription from the group
- API
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’ssubscription_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_paidgoes up,amount_remaininggoes down, andpayment_statusstaysPENDINGuntil 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_remainingreaches zero.
Credit notes
Credit notes on a grouped invoice work line by line. To credit one subscription, reference that subscription’s line items inline_items:
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.
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’sexternal_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
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
Can I preview whether a subscription can be added to a group?
Can I preview whether a subscription can be added to a group?
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.What happens to the children when the parent subscription is cancelled?
What happens to the children when the parent subscription is cancelled?
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.What happens if I cancel one child subscription in the group?
What happens if I cancel one child subscription in the group?
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.Can I refund only one subscription's charges on a grouped invoice?
Can I refund only one subscription's charges on a grouped invoice?
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.
Can I have both grouped invoicing children and inherited children under the same parent subscription?
Can I have both grouped invoicing children and inherited children under the same parent subscription?
No. A subscription has one type. Grouped invoicing and consolidated billing use different mechanisms and cannot be mixed on the same parent subscription.
Related workflows
Consolidated Billing
When one parent plan should cover multiple customers
Delegated Invoicing
When a third party should receive the invoice for a standalone subscription

