Mixed interval subscriptions
Manage subscriptions for items with different intervals.
You can include multiple subscription items with different prices and billing periods on a single subscription and Stripe automatically handles invoice generation.
For example, if you offer a service with an annual flat rate, plus a monthly usage-based fee, you can include both prices as items on the same subscription. Stripe generates a single, combined invoice when item-level billing periods align and separate invoices when billing periods diverge.
Note
Mixed interval subscriptions must use flexible billing mode. You must upgrade your API version to 2025-06-30.basil or later to use flexible billing mode in the Dashboard and API.
Create a mixed interval subscription
- Go to the Subscriptions page in the Dashboard.
- Select +Create Subscription .
- Add products that bill on different intervals, such as monthy and yearly billing periods. Learn how to manage products and prices .
- Configure your Subscription settings .
- Scroll down to the Advanced settings section, set Billing mode to Flexible .
- Create the subscription.
Add mixed interval items to an existing subscription
- Go to the Subscriptions page in the Dashboard.
- Find the subscription and click +Update Subscription .
- Scroll down to the Advanced settings section, set Billing mode to Flexible .
- Click +Update Subscription .
- Find the subscription and click +Update Subscription again.
- Add items with different intervals.
- Create the subscription.
Cancel a subscription
Canceling a mixed interval subscription or schedule cancels all the subscription items, regardless of their interval.
Subscriptions have a single behavior for dunning. If all retries for a payment fail, even if the failing payment is for an invoice related to only one of the items on the subscription, Stripe cancels the entire subscription and marks it as unpaid or past due, depending on your configured dunning settings.
Learn more about canceling or deleting subscriptions.
Billing periods for mixed interval subscriptions
Each subscription item has its own current_period_start and current_period_end. Subscription items track their respective billing periods directly instead of as a top-level shared billing period on the subscription resource.
For example, a subscription created on January 1 with a monthly, bimonthly, and quarterly item has the following periods:
| current_period_start | current_period_end | |
|---|---|---|
| Monthly item | January 1 | February 1 |
| Bi-monthly item | January 1 | March 1 |
| Quarterly item | January 1 | April 1 |
| Subscription | January 1 | February 1 |
After renewal on February 1 ( subscription.current_period_end), the subscription’s current period adjusts to match the latest current_period_start and earliest current_period_end of all the items:
| current_period_start | current_period_end | |
|---|---|---|
| Monthly item | February 1 | March 1 |
| Bi-monthly item | January 1 | March 1 |
| Quarterly item | January 1 | April 1 |
| Subscription | February 1 | March 1 |
After cycling a third time:
| current_period_start | current_period_end | |
|---|---|---|
| Monthly item | March 1 | April 1 |
| Bi-monthly item | March 1 | May 1 |
| Quarterly item | January 1 | April 1 |
| Subscription | March 1 | April 1 |
Free trial
The item-level billing period dates are affected by free trial end dates, similar to regular subscriptions. When the subscription has a future-dated trial_end, all the current_period_end dates (subscription and items) are set to the trial_end date.
Pause at trial end and resume
You can configure a mixed interval subscription to pause at trial end when the payment method is missing through the trial_settings.end_behavior.missing_payment_method parameter as with regular subscriptions. You can resume paused subscriptions using stripe.subscription.resume, as with regular subscriptions.
Note
When resuming a mixed interval subscription with billing_cycle_anchor: 'unchanged' and proration_behavior: 'none', the debit proration for the partial period between the date of resumption and the end of the current billing period for each of the items aren’t generated or billed. See an example below:
For a mixed interval subscription with a monthly and a bimonthly item with
- billing _ cycle _ anchor = January 1
- trial _ end = February 1
- trial _ settings. end _ behavior. missing _ payment _ method = “pause”
This example assumes this subscription is paused on February 1 because of a missing payment method, and the subscription resumes on February 15 with proration_behavior: 'none':
| billing_cycle_anchor: ‘unchanged’ | billing_cycle_anchor: ‘now’ | |
|---|---|---|
| Monthly item | Item current period: February 1–March 1 Not billing for this period, so no new invoice is created Monthly item is next billed on March 1 for the period March 1–April 1 | Item current period: February 15–March 15 Generates a new invoice, and bills for a monthly item from February 15–March 15 |
| Bimonthly item | Item current period: February 1–April 1 Not billing for this period, so no new invoice is created Bimonthly item is next billed on April 1 for the period April 1–June 1 | Item current period: February 15–April 15 Generates a new invoice and bills for a monthly item from February 15–April 15 |
| Subscription | billing_cycle_anchor: February 1 Subscription transitions to active immediately | Generate a subscription pending update for billing_cycle_anchor: February 15 (applied when resumed invoice is paid) Subscription remains paused until resumption invoice is paid |
Interval alignment
In mixed interval subscriptions, every item’s price interval (the combination of price.recurring.interval and price.recurring.interval_count) must be a multiple of the shortest price interval in the subscription. Some price interval combinations aren’t supported for mixed interval subscriptions.
- Examples of supported interval combinations:
- 1 month, 3 months
- 1 month, 1 year
- 1 day, 1 week
- 1 day, 3 months
- 1 day, 2 years
- 2 weeks, 4 weeks
- 2 months, 4 months, 6 months
- Examples of unsupported interval combinations:
- 2 months, 3 months
- 4 months, 6 months
- 1 week, 1 month
- 2 days, 1 week
- 5 months, 1 year
Limitations
Mixed interval subscriptions are subject to the following limitations:
- The deprecated cancel_at_period_end can’t detect which subscription item’s current _ period _ end to use as the cancellation date. It defaults to the earliest item period end. Instead, use cancel_at with one of these special values:
- min _ period _ end : Cancels the subscription at the earliest current _ period _ end across all items.
- max _ period _ end : Cancels the subscription at the latest current _ period _ end across all items.
- max _ billed _ until : Cancels the subscription at the latest date any item is billed through.
- An explicit Unix timestamp for a custom cancellation date.
- Mixed interval subscription schedules can’t calculate total iterations accurately. Use duration to specify the phase length instead.
- You can’t apply a retention coupon on mixed interval subscriptions through the customer portal.
- You currently can’t create mixed interval subscriptions on Checkout Sessions .