Enable increased flexibility for subscriptions

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

Flexible billing mode is a subscription setting that provides more accurate and predictable billing behaviour and unlocks access to additional features. You can enable flexible billing mode by setting billing_mode[type] = flexible (with the API or Dashboard) on a subscription. With flexible mode enabled, you can:

Improve how credit prorations are calculated.
Simplify invoicing for metered usage.
Get enhanced trial functionality.
Gain more reliable control over the subscription lifecycle.
Enable a different proration logic that calculates credit prorations based on the original amount previously debited to a customer.
Access additional features, such as mixed intervals on the same subscription.

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.

There are a few limitations to consider when using flexible billing mode:

You can’t do a downgrade from flexible billing mode to classic billing mode.
You can’t enable flexible billing mode on a subscription that uses billing thresholds.
You can’t enable flexible billing mode on a subscription that uses legacy usage-based billing.

Configure billing mode

Create a new subscription with flexible billing mode

You can create and update subscriptions with a flexible billing mode in 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.

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

Migrate existing subscriptions to flexible billing mode

You can migrate your existing subscriptions to flexible billing mode.

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’d like to migrate.
Select Actions and then Update subscription.
Scroll down to the Advanced settings section.
Set Billing mode to Flexible and select Update subscription.

Flexible billing mode enhancements

Setting billing_mode=flexible on a subscription changes how Subscription objects behave throughout their lifecycle and in response to upgrades, downgrades, and cancellations.

Credit proration calculations

Flexible billing mode calculates credit prorations based on the original amount previously debited to a customer. For a full overview of credit proration calculations, see Credit prorations.

Classic	Flexible
When an update to a subscription generates a credit proration, previously the credit proration amounts are calculated based on the value of the subscription item’s current price, tax, quantity, and the last discounts used.	When an update to a subscription generates a credit proration, these prorations now use the original debited amount from instead of current subscription values.

Proportional discount application for prorations

We apply discounts proportionally to each subscription item during proration calculations instead of distributing them evenly. This results in more prorations, especially when invoicing on a per-item basis or cancelling items with unevenly distributed discounts.

Classic	Flexible
We distribute discounts evenly across all subscription items.	We apply discounts proportionally to each subscription item during proration calculations.

Metered pricing

Suppresses zero-amount line items when adding metered items

Flexible billing mode doesn’t create zero-amount line items when you add metered items to a subscription. If the invoice is empty as a result, we don’t generate one.

For example, when adding a monthly metered item during subscription creation or update:

Classic	Flexible
A 0 USD line item is generated on the invoice for the metered item. This also applies when updating a subscription without cycling to add a metered item while using `proration_behavior=always_invoice`.	A 0 USD line item isn’t added to the invoice for the metered item. If the invoice ends up “empty”, no invoice is generated at all

Bills metered usage based on price at time of reporting

Flexible billing mode charges for usage based on the price that was in effect when the usage was reported, rather than the most recent price.

For example, a customer’s usage is reported as:

Usage on 5 January: 1000 API calls at 0.1 USD per 100 calls (Price A).
Price change on 15 January: The price changes to 0.15 USD per 100 calls (Price B).

Usage on 20 January: 500 API calls.

Classic	Flexible
All usage, regardless of when it’s reported, is billed at Price B Total charges: 1000 API calls at 0.15 USD = 150 USD 500 API calls at 0.15 USD = 75 USD Total invoice amount = 225 USD.	Usage is billed at the price effective at the time it’s reported. Total charges: 1000 API calls at Price A (0.1 USD) = 100 USD 500 API calls at Price B (0.15 USD) = 75 USD Total invoice amount = 175 USD.

Bills for unbilled usage when removing metered items

Flexible billing mode generates an invoice item for unbilled usage when removing a metered subscription item. This applies to removals using the API or during schedule phase transitions.

Classic	Flexible
No invoice item is generated for unbilled usage when removing a metered subscription item.	An invoice item is generated for unbilled usage when removing a metered subscription item.

Billing cycle anchor resets

Flexible billing mode only resets your billing cycle anchor on subscription updates when you explicitly set billing_cycle_anchor to a value other than unchanged.

Classic	Flexible
The `billing_cycle_anchor` is automatically reset to the current date when switching a subscription to a different price with a different recurring interval, from zero-amount prices to non-zero price or moving cancel_at to a date before the next time the subscription cycles.	The `billing_cycle_anchor` is never automatically reset.

Consolidated invoicing for subscription schedule phase transitions with metered items

Flexible billing mode consistently generates a single invoice when a subscription cycles. This change eliminates separate invoices for removed metered items and improves billing consistency.

When your subscription with metered items transitions between phases:

Classic	Flexible
Two invoices are generated.	A single consolidated invoice is generated. This invoice includes both metered and licensed items, applies discounts from the previous phase to metered usage, and uses tax rates from the next phase.

Scheduled cancellation

You can now disable prorations for a truncated first subscription period (when setting cancel_at on creation) using the proration_behavior parameter.

Classic	Flexible
Prorations are applied to the first subscription period.	Prorations are not applied to the first subscription period.

Backdating

Backdating is consistent with regular billing

Flexible billing mode creates separate invoice line items for each billing period within the backdated range. It also automatically aligns the billing cycle anchor to the backdate_start_date when not explicitly set. Backdating isn’t supported if the resulting invoice has more than 250 line items.

For example, a subscription needs to be backdated due to a missed invoice for the past two billing cycles. The customer was invoiced for 2 different backdated periods:

Billing Period 1 (1 March – 31 March):
- Usage reported: 100 GB of storage used.
- Price: 10 USD per 10 GB.

Billing Period 2 (1 April – 30 April):

Usage reported: 150 GB of storage used.
Price: 10 USD per 10 GB.

The service provider decides to backdate the invoice to cover both billing periods: 1 March to 30 April.

Classic	Flexible
Charges for the entire backdated period are calculated collectively as a single line item. Total charges: 250 GB = 25 x 10 USD = 250 USD This amount appears as a single line item on the invoice.	Backdated time ranges are split into multiple invoice line items according to subscription period boundaries. Total charges: Billing Period 1 (March): 100 GB = 10 x 10 USD = 100 USD (as a separate line item). Billing Period 2 (April): 150 GB = 15 x 10 USD = 150 USD (as a separate line item).

Trials

Update trial start date for subsequent trials

Flexible billing mode uses the most recent trial start date for subscriptions with subsequent trials.

For example, when you have:

Trial period from 1 January to 1 February
Normal billing period from 1 February to 1 March
Trial period from 1 March to 1 April

Classic	Flexible
The `subscription.trial_start` always refers to the first trial a subscription started.	The `subscription.trial_start` refers to the start of the most recent trial of a subscription.

Preserve original trial end date when subscription cancels

Flexible billing mode preserves the trial_end if you modify the cancel_at date.

Classic	Flexible
If `trial_end` date is later than `cancel_at`, `trial_end` is set to the cancellation date. If `cancel_at` is later updated or removed `trial_end` isn’t set to its original value.	Scheduling a subscription cancellation using `cancel_at` no longer alters the `trial_end` date. This ensures that trials run for their intended duration regardless of cancellation date updates.

Standardise trial period line item description

Flexible billing mode uses a consistent description format for both metered and licensed items during trial periods.

For example, when you have a monthly coffee subscription (licensed) and alpaca_ai_tokens subscription (metered), the subscription description displays as following:

Classic Flexible

Classic	Flexible
Licensed items use the template `Trial period for {product name}`, while metered items use `{quantity} x {product name} (Free trial)`. For licensed items: `Trial period for monthly coffee subscription` For metered items: `10 x monthly alpaca_ai_tokens (Free trial)`	The same format, `Free trial for {quantity} x {product name}`, applies to all item types, which provides a more uniform presentation of trial information. These descriptions are also localised. For licensed items: `Free trial for 1 x monthly coffee subscription` For metered items: `Free trial for 10 x monthly alpaca_ai_tokens subscription`

Licensed items use the template Trial period for {product name}, while metered items use {quantity} x {product name} (Free trial).

For licensed items:
- Trial period for monthly coffee subscription
For metered items:
- 10 x monthly alpaca_ai_tokens (Free trial)

The same format, Free trial for {quantity} x {product name}, applies to all item types, which provides a more uniform presentation of trial information. These descriptions are also localised.

For licensed items:
- Free trial for 1 x monthly coffee subscription
For metered items:
- Free trial for 10 x monthly alpaca_ai_tokens subscription

Re-billing for trial line items

Flexible billing mode only generates line items for changes made during a trial. Existing items without changes aren’t rebilled.

For example, when you make an update to add another trial item price_b to a trialing subscription with price_a:

Classic	Flexible
Changes during a trial result either in no invoice or in an invoice that restates the entire state of the subscription.	Changes during a trial consistently result in line items comparable to changes outside a trial. For example, if a new price is added to a subscription a line item representing that addition is also added.

Pending Invoice items

Consistently include pending invoice items

Flexible billing mode includes all available pending invoice items in invoices generated by a billing cycle anchor reset where proration_behavior = always_invoice.

Classic	Flexible
Billing cycle anchor reset invoices include pending items, while `always_invoice` invoices don’t.	Pending invoice items are always included on all invoices a subscription generates.

Mixed intervals on the same subscription Private preview

Flexible billing mode allows you to access mixed interval subscriptions. You can bill for multiple recurring prices with different intervals on a single subscription using mixed interval subscriptions. This allows you to combine different pricing structures within a single subscription.

Classic	Flexible
Not supported. All items in a subscription must have prices with the same interval and interval count.	Create mixed interval subscriptions, where items on a subscription can have recurring prices with different intervals or interval counts. For example, a monthly price and an annual price can exist on the same subscription.

Limitations

Flexible billing mode isn’t compatible with all Stripe Billing features. The following features are currently incompatible and return a 400 error code when you create and update a subscription:

Pre-billing Private preview
Paid trials
Legacy usage-based billing
Legacy third-party tax integrations using pay_immediately=false
The use of the legacy max_occurences parameter
Subscription specific retry_settings Private preview
Billing thresholds