Mixed interval subscriptions

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.

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:

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:

After cycling a third time:

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.

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:

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, 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.