Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
    Overview
    How subscriptions work
    Get started
    Quickstart
    Plan an integration
    Build an integration
    Use cases
    About subscriptions
    Enable billing mode
    Subscription event definitions
    Entitlements
    Subscription invoices
    Subscription schedules
    Recurring pricing models
    Strong Customer Authentication (SCA)
    Set up subscriptions
    Configure collection methods
    Embed a pricing table
    Set quantities
    Set billing cycles
    Manage subscriptions
    Migrate subscriptions to Stripe
    Subscribe to multiple items
      Mixed interval subscriptions
    Backdate subscriptions
    Set trial periods
    Handle subscriptions with deferred payment
    Apply coupons
    Modify subscriptions
    Manage subscription payment methods
    Analytics
Invoicing
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueSubscriptionsSubscribe to multiple items

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 intervals align and separate invoices when intervals diverge.

Note

Mixed interval subscriptions must use flexbile billing mode. You must upgrade your API version to 2025-06-30.basil or later to use flexbile billing mode in the Dashboard and API.

Create a mixed interval subscription

  1. Go to the Subscriptions page in the Dashboard.
  2. Select +Create Subscription.
  3. Add products that bill on different intervals, such as monthy and yearly billing intervals. Learn how to manage products and prices.
  4. Configure your Subscription settings.
  5. Scroll down to the Advanced settings section, set Billing mode to Flexible.
  6. Create the subscription.

Add mixed interval items to an existing subscription

  1. Go to the Subscriptions page in the Dashboard.
  2. Find the subscripton and click +Update Subscription.
  3. Scroll down to the Advanced settings section, set Billing mode to Flexible.
  4. Click +Update Subscription.
  5. Find the subscripton and click +Update Subscription again.
  6. Add items with different intervals.
  7. 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_startcurrent_period_end
Monthly itemJanuary 1February 1
Bi-monthly itemJanuary 1March 1
Quarterly itemJanuary 1April 1
SubscriptionJanuary 1February 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_startcurrent_period_end
Monthly itemFebruary 1March 1
Bi-monthly itemJanuary 1March 1
Quarterly itemJanuary 1April 1
SubscriptionFebruary 1March 1

After cycling a third time:

current_period_startcurrent_period_end
Monthly itemMarch 1April 1
Bi-monthly itemMarch 1May 1
Quarterly itemJanuary 1April 1
SubscriptionMarch 1April 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. We only support the proration_behavior: 'none' and billing_cycle_anchor parameters with mixed interval 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 itemItem 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 itemItem 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:

    Equivalent intervals

    When validating that the intervals on your subscription align, Stripe considers the following intervals as equivalent:

    • 1 week and 7 days
    • 12 months and 1 year
    • 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:

    Non equivalent intervals

    There are no equivalences between the following price interval types:

    • Week and month
    • Week and year
    • Day and month
    • Day and year
    • 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, so defaults to min_period_end. Alternatively:
    • Use the cancel_at parameter to cancel a subscription on a future date.
    • Use the min_period_end or max_period_end helpers to determine which item’s end period triggers the subscription cancelation.
  • Mixed interval subscriptions can’t calculate total iterations accurately. Use duration to specify the subscription schedule 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.
Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Join our early access program.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc