Breaking changes

Makes flexible billing mode the default for new subscriptions Breaking changes

What’s new

Subscriptions you create through the API now default to flexible billing mode. To use classic, set the billing_mode.type parameter to classic.

In the Stripe Dashboard, use Billing Settings to set an account-wide default billing mode for subscriptions you create with the subscription editor and payment links. You can display both billing modes and set the default to flexible or classic, or hide classic entirely. You can also configure billing mode behavior for subscriptions created through payment links and pricing tables.

Why is this a breaking change?

Flexible billing mode changes subscription behavior and invoice calculations compared to classic. Review the differences.

It gives you accurate, predictable billing and additional features to manage subscriptions. This new default impacts these integrations:

• Create a subscription
• Create an invoice preview
• Create a subscription schedule
• Create a quote
• Subscriptions created through the Checkout Session API
• Subscriptions created through the Payment Link API

Impact

For API users, the default billing mode depends on the request API version:

• If the request API version is 2025-09-30.clover or newer, the default is flexible billing mode.
• If the request API version is older than 2025-09-30.clover , the default is classic billing mode.

For Dashboard users, the default billing mode is linked to the newly introduced Billing Mode Settings:

• New Stripe Billing users (those who’ve never created a subscription in live mode or test mode) only see flexible billing mode as the option.
• Existing users see both flexible and classic billing modes, with classic selected by default.
• You can configure the default Billing Mode Settings in your Billing settings.

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-09-30. clover

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

• Removes iterations parameter for subscription schedules
• Promotion Codes now reference Coupons using a polymorphic field for promotions
• Adds the Discount source property and removes the Discount coupon property
• Updates computation of subscription schedule phase end date to consider billing cycle anchor changes
• Adds customer portal configuration trial behavior
• Adds the ability to itemize proration discount amounts