Consolidate invoices across multiple subscriptionsVersion bêta publique

When you set a billing cadence on a subscription, invoice items get generated at the end of billing periods (instead of invoices) and the billing cadence takes over the responsibility of invoice generation.

Billing Cadences is in public preview.

Example use case

Imagine a fictional design company called Typographic. They need a single customer to pay for multiple subscriptions.

In this scenario, John Appleseed is a customer, has a monthly subscription to Typographic, and he wants to add a second subscription. Typographic wants to deliver a single invoice for both subscriptions to reduce their invoice processing costs, and provide a better user experience.

1. Typographic creates a Customer for John.
2. Typographic creates a subscription for John with the billing_cycle_anchor_config set to the 15th of the month.
3. On the 10th of the month, Typographic creates a second subscription with the billing_cycle_anchor_config set to the 15th of the month.

So far, these subscriptions generate their own invoices even though they bill on the same date. To consolidate these, we need a billing cadence.

Create a billing profile

Typographic creates a billing profile which will pay for the consolidated invoice. They decide to copy details from John’s customer object.

curl -X POST https://api.stripe.com/v2/billing/profiles \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "customer": 
{{CUSTOMER_ID}}
  }'

Create a Billing Cadence

Typographic creates a billing cadence which has a monthly interval that starts on the 15th day of the month and sets John’s billing profile object as the payer for this billing cadence.

curl -X POST https://api.stripe.com/v2/billing/cadences \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "payer": {
        "billing_profile": "bilp_x"
    },
    "billing_cycle": {
        "type": "month",
        "month": {
            "day_of_month": 15
        }
    }
  }'

Update the subscriptions to use the cadence

This update means all invoice items generated from this subscription will be included in the next billing cadence billing cycle.

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d billing_cadence=bc_x

On the 15th of the month, the billing cadence cycles and invoices for both subscriptions on a single unified invoice.

Features

• Subscription status: When an Invoice is paid or fails to be paid, the subscription status of all subscriptions linked to the billing cadence update accordingly.

• Invoice previews: To generate a preview invoice for a billing cadence, use the billing_cadence parameter on the create preview API endpoint. The next billing cadence invoice is generated, including any subscription invoice that will be generated from now until the next billing date.

• Trials: Even when subscriptions are associated with a billing cadence, trials ending still generate an invoice.

• Discounts: We apply subscription discounts across all invoice items related to that subscription during billing cadence invoice generation. Subscription item discounts apply to each invoice item related to that subscription item.

• Invoice-related properties on the Subscription: When you associate subscriptions with a billing cadence, many properties which are related to invoicing are set to nil. For example, invoice_settings.

Restrictions

• Customers must be the same between all subscriptions
• Currency must be the same between all subscriptions

Limitations

• You can’t create multiple subscriptions at the same as a billing cadence.
• Maximum of 200 subscription items per billing cadence.