Adds support for mixed intervals on the same subscription
What’s new
A single subscription can now bill for multiple recurring prices with different intervals. For example, a subscription can have both an annual flat fee and a monthly usage-based fee. Previously, all items on the same subscription needed to have the same interval.
Mixed-interval subscriptions are supported in API version 2025-07-30.basil or later and require the Subscription to be configured in flexible billing mode.
Impact
You can now create subscriptions with items of different intervals through the Dashboard and using any of the following APIs:
- Subscriptions
- Subscription Schedules
- Quotes
Verify that your integration can correctly process subscriptions where subscriptions.items.current_period_[start|end] differs between items. If your integration reads mixed interval subscriptions using API versions before 2025-03-30.basil, the top-level current_period_[start|end] will reflect the smallest item level period. If your subscription is configured to billing_mode=classic, you must first set its billing_mode to flexible using the migrate endpoint.
Learn more about mixed-interval subscriptions.
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2025-07-30. basil
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.