Enable increased flexibility for subscriptions

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.

You can learn more about the detailed differences between classic and flexible billing mode and how to choose the billing mode that works best for you.

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 value for billing mode depends on your API integration version.
• 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

Dashboard

API

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:

1. Go to the Subscriptions page in the Dashboard.
2. Select +Create Subscription.
3. Scroll down to the Advanced settings section.
4. Set Billing mode to Flexible.

The default billing mode value depends on your account settings. You can customize the displayed billing mode options and the default selection in Advanced settings by configuring the billing mode default setting under Settings > Billing > Subscriptions and emails. 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 cannot 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 are 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.

Dashboard billing mode settings

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.

Billing mode and subscription schedules

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. If you need a different billing_mode, create a new subscription.

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.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-06-30.basil" \
  -d "items[0][price]"=
"{{PRICE_ID}}" \
  -d customer=
"{{CUSTOMER_ID}}" \
  -d "billing_mode[type]"=flexible \
  -d "billing_mode[flexible][proration_discounts]"=itemized \
  -d payment_behavior=default_incomplete \
  -d "payment_settings[save_default_payment_method]"=on_subscription

The code example above returns the following response:

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