Enable increased flexibility for subscriptions

Use flexible billing mode for enhanced functionality and to access additional features.

You can set your preferred billing mode to orchestrate your invoices and subscriptions to meet your business requirements. You can configure each subscription to use one of two billing modes:

Flexible Recommended : Provides accurate and predictable billing behavior and new capabilities. To access these improvements, which are only available in flexible billing mode, you must create new subscriptions with flexible billing mode or migrate your existing subscriptions.
Classic : Uses the existing Stripe subscription behavior. This setting is maintained for backward compatibility with older integrations.

Compare classic versus flexible billing mode.

Warning

You can’t migrate a subscription from flexible billing mode to classic billing mode.

Why flexible billing mode

Flexible billing mode provides more accurate billing for prorations, usage-based pricing, flexible invoicing, and trial settings. It also unlocks new capabilities such as mixed intervals on the same subscription. These improvements are only available in flexible billing mode, which is why we recommend creating new subscriptions with flexible billing mode and migrating your existing ones.

We recommend that new Billing users use flexible billing mode for subscriptions and invoices, although we don’t require it.

For existing users, your default billing mode is preserved as classic to maintain backward compatibility with your current integration. However, we recommend migrating to flexible billing mode to take advantage of the latest billing features and improvements. Learn more about the differences between classic and flexible billing mode.

Get started with flexible billing mode

You can set or update the billing mode through the API or Dashboard when you create or migrate subscriptions. We apply a default billing mode if you don’t specify one.

If you create or update a subscription through the API, the default billing mode depends on your API integration version . For API version 2025-09-30. clover and later, the default is flexible . For earlier versions, the default is classic . If you upgrade your API version , the default billing mode for new subscriptions changes accordingly.
If you create or update subscriptions through the Dashboard (including Payment Links and Pricing Tables ), the default value depends on the billing mode default setting you configure in Settings > Billing > Subscriptions and emails .

To use flexible billing mode, your integration must be on Stripe API version 2025-06-30.basil or later. Learn how to upgrade your API version.

Create a new subscription with flexible billing mode

You can create a flexible billing mode subscription or update a classic billing mode subscription to be flexible through the Dashboard, regardless of your integration’s API version. To fully modify these subscriptions in the Stripe API, your integration must be on 2025-06-30.basil or later. To see what version you’re on, go to the Workbench overview and look at the API versions section. From there, click Upgrade to upgrade to a newer version.

Follow the steps below to create a flexible billing mode subscription through the subscription editor:

Go to the Subscriptions page in the Dashboard.
Click Create Subscription .
Expand the Billing and payment collection section.
Set Billing mode to Flexible

The default billing mode value depends on your account settings. You can customize both the available billing mode options and the default selection in the Subscription editor. To configure this, go to Settings > Billing > Subscriptions and emails > Default billing mode. In the subscription editor, you can choose to display billing mode options from the following:

Classic: Both flexible and classic billing modes are displayed, with classic selected by default. This option is recommended if your integration depends on classic billing mode and you can’t migrate to flexible billing yet.
Flexible: Both flexible and classic billing modes are displayed, with flexible selected by default. This option is recommended if you’re actively migrating to flexible billing mode.
Flexible and hide classic: Only flexible billing mode is displayed in the subscription editor. This option is recommended for new Stripe Billing users and for existing users who exclusively use flexible billing mode.

The billing mode default setting also determines the billing mode for subscriptions created through Dashboard-generated Payment Links and Pricing Tables. For example, if you set the billing mode default to flexible and then create a Payment Link in the Dashboard, any subscription generated from that Payment Link uses flexible billing mode.

The billing mode default setting only applies to new subscriptions created in the Dashboard. It doesn’t affect subscriptions created using the API or subscriptions migrated to flexible mode.

Migrate existing subscriptions to flexible billing mode

You can migrate your existing subscriptions to flexible billing mode. The flexible behaviors take effect for all new activity on the subscription after migration. However, Stripe doesn’t recalculate any resources created before migration, including pending proration Invoice Items.

To use flexible billing mode, your integration must be on Stripe API version 2025-06-30.basil or later. To see what version you’re on, go to the Workbench overview and look at the API versions section. From there, click Upgrade to upgrade to a newer version.

On the Subscriptions page in the Dashboard, select the subscription that you want to migrate.
Click Update subscription .
Scroll down to the Advanced settings section.
Set Billing mode to Flexible and select Update subscription .

What changes after migration

Migrating to flexible billing mode changes how Stripe calculates prorations, handles usage-based billing, and processes cancellations for all new activity on the subscription after migration. Stripe doesn’t recalculate any resources created before migration, including pending proration invoice items.

Key consequences of migrating:

Credit prorations use the original debited amount instead of current subscription values.
Usage-based billing charges at the price in effect when usage was reported.
The billing cycle anchor is never automatically reset.
You can’t revert a subscription from flexible billing mode back to classic billing mode.

Key benefits of migrating:

Access to new capabilities such as mixed interval subscriptions and trial offers .
More accurate and predictable proration calculations.
Consistent handling of usage-based items during mid-cycle subscription changes.

For a full breakdown of behavior differences, see Compare classic and flexible billing mode.

Billing mode and subscription schedules

You can migrate a subscription with an active subscription schedule to flexible billing mode using the migrate API. The Dashboard doesn’t support billing mode migration for subscriptions with active schedules. When you migrate through the API, Stripe also updates the subscription schedule’s billing_mode automatically.

Caution

If a subscription schedule hasn’t started yet and has no active subscription, you can’t migrate it. Cancel and recreate the schedule with billing_mode set to flexible.

When you create a subscription schedule from an existing subscription, don’t set billing_mode if the subscription already has one. The schedule automatically inherits the billing_mode from the original subscription. If you set billing_mode when using from_subscription, Stripe returns an error.

Itemize proration discounts

If you use flexible subscriptions, you can set your preferred behavior for proration discounts on invoices and invoice items:

Itemized Recommended : Enables invoices and invoice items to show prorations with gross amounts and accurate discount amounts, consistent with non-prorations.
Included : Uses the existing Stripe proration display behavior, with net amount and zero monetary discount amounts. This setting is maintained for backward compatibility with older integrations.

Learn more about the differences between itemized and included.

To enable itemized proration discounts, you must upgrade your API version to 2025-06-30.basil or later.

Create or migrate a subscription in order to set proration_discounts to itemized.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

The code example above returns the following response:

{
 "id": "sub_JgRjFjhKbtD2qz",
 "object": "subscription",
 "billing_mode": {
 "flexible": {
 "proration_discounts": "itemized"
 },
 "type": "flexible",
 "updated_at": 1751071020
 },