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.

Compare classic versus flexible 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 dont 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 dont 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

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 doesnt recalculate any resources created before migration, including pending proration Invoice Items.

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 doesnt 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 cant 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 doesnt support billing mode migration for subscriptions with active schedules. When you migrate through the API, Stripe also updates the subscription schedules billing_mode automatically.

When you create a subscription schedule from an existing subscription, dont 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.

curl https://api.stripe.com/v1/subscriptions \
  -u "sk_test_wU7nrJCZspk1NPDxiQgAF05q:" \
  -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
  },