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

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_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -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
  },