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
Versioning
Changelog
    Overview
    Basil
    Acacia
    Previous versions
Upgrade your API version
Upgrade your SDK version
Essentials
SDKs
API
Testing
Stripe CLI
Sample projects
Tools
Workbench
Developers Dashboard
Stripe Shell
Stripe for Visual Studio Code
Features
Workflows
Event destinations
Stripe health alertsFile uploads
AI solutions
Agent toolkit
Model Context Protocol
Security and privacy
Security
Privacy
Extend Stripe
Build Stripe apps
Use apps from Stripe
Partners
Partner ecosystem
Partner certification
HomeDeveloper resourcesChangelogBasil2025-07-30.basil

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

  1. View your current API version in Workbench.
  2. 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
  3. Upgrade the API version used for webhook endpoints.
  4. Test your integration against the new version.
  5. If you use Connect, test your Connect integration.
  6. In Workbench, perform the upgrade. You can roll back the version for 72 hours.

Learn more about Stripe API upgrades.

Related changes

  • Adds a duration parameter for schedule phases
  • Adds support for quantity adjustment to the Customer Portal Configuration API
  • Adds helpers to cancel subscriptions for billing periods with mixed intervals
  • Adds support for billing thresholds on flexible billing mode Subscriptions
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