Mixed interval subscriptionsPrivate Vorschau

You can bill for multiple recurring prices with different intervals on a single subscription using mixed interval subscription. This allows you to combine different pricing structures within a single subscription.

For example, if a customer subscribes to a service with an annual flat fee of 500 USD and a monthly usage-based fee, you can include both prices as items on the same subscription. Stripe generates combined invoices when item-level billing cycles align and generates separate invoices when only one item is due.

Get started with mixed interval subscriptions

To enable mixed interval subscriptions, you must set billing_mode=flexible on the following API endpoints and upgrade your API version to 2025-04-30.preview or later.

• Create a subscription
• Create a preview invoice
• Create a Checkout Session

Create a subscription with mixed intervals

Create a subscription using prices of different recurring interval values to invoice for subscription items renewing at disjoint times.

For the example of a 100 USD per quarter and a 15 USD per month subscription starting on January 1 2024, create the following subscription:

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "items[0][price_data][currency]"=usd \
  -d "items[0][price_data][product]"=
{{PRODUCT_ID}} \
  -d "items[0][price_data][recurring][interval]"=month \
  -d "items[0][price_data][recurring][interval_count]"=1 \
  -d "items[0][price_data][unit_amount]"=1500 \
  -d "items[0][quantity]"=1 \
  -d "items[1][price_data][currency]"=usd \
  -d "items[1][price_data][product]"=
{{PRODUCT_ID}} \
  -d "items[1][price_data][recurring][interval]"=month \
  -d "items[1][price_data][recurring][interval_count]"=3 \
  -d "items[1][price_data][unit_amount]"=10000 \
  -d "items[1][quantity]"=1 \
  -d collection_method=send_invoice \
  -d days_until_due=5 \
  -d proration_behavior=none \
  -d billing_mode=flexible \
  -d "expand[0]"=latest_invoice

The response includes a subscription with both items and bills for them on the first invoice (latest_invoice):

{
  "object": "subscription",
  "id": 
'{{SUBSCRIPTION_ID}}',
  "current_period_start": 1704067200, // Jan 1 2024
  "current_period_end": 1706745600, // Feb 1 2024
  "items": {
    "data": [
      {
        "id": "si_A",
        "price": "price_id_monthly",

On February 1 and March 1, the subscription renews and generates a new invoice for the monthly price. On April 1, the subscription renewal creates an invoice for both the monthly and quarterly price.

Cancel a subscription

• When you cancel a mixed interval subscription or schedule, Stripe cancels all the subscription items, regardless of their interval.
• Subscriptions have a single behavior for dunning, even if an invoice only bills for one of the items on the subscription. If all retries for a payment fail, Stripe cancels the entire subscription and marks it as unpaid or past due, depending on your configured dunning settings.

Billing periods for mixed interval subscriptions

Each subscription item has its own current_period_start and current_period_end.

Stripe sets the subscription’s current period based off the subscription item’s billing periods, where:

• current_period_start is the maximum of the item’s current_period_start dates.
• current_period_end is the minimum of the item’s current_period_end dates.

The subscription.current_period_end always indicates the next date that an item will cycle.

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:

Adjustments to billing periods

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

A mixed interval subscription can be configured 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. Paused subscriptions can be resumed using stripe.subscription.resume, as with regular subscriptions. Currently, only proration_behavior: none and billing_cycle_anchor parameters are supported.

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:

Mixed interval considerations

There are several restrictions introduced with the mixed interval feature.

Cycle alignment

The price cycle of every subscription item must be a multiple of the shortest price cycle present on the subscription. A price’s interval is a combination of the price.recurring.interval and price.recurring.interval_count fields.

• 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

While in private preview, mixed interval subscriptions are subject to the following limitations that might change during development:

• All subscription item prices must specify recurring.usage_type: licensed and billing_scheme: per_unit. We don’t support metered pricing.
• Mixed interval subscriptions are currently available in the Stripe API only, and not the customer portal.
• You can’t use cancel_at_period_end on a mixed interval subscription because it’s unclear which subscription item’s current_period_end to use to determine the cancellation date.