Enable increased flexibility for subscriptions
Use flexible billing mode for enhanced functionality and to access additional features.
Flexible billing mode provides accurate and predictable billing behavior and additional features for managing subscriptions. Setting billing_
on a subscription changes how Subscription objects behave throughout their lifecycle and in response to upgrades, downgrades, and cancellations.
Flexbile billing mode enables different capabilities for managing subscriptions than classic billing mode does. See Differences between classic and flexible billing mode for details.
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. You can’t downgrade from flexible billing mode to classic billing mode.
Limitations
Flexible billing mode isn’t compatible with all Stripe Billing features. The following features are incompatible and return a 400 status code when you create and update a subscription with flexible billing mode enabled:
- Paid trials
- Legacy usage-based billing
- Legacy third-party tax integrations using
pay_
immediately=false - Prebilling Private preview
- Subscription-specific
retry_
Private previewsettings - The use of the legacy
max_
parameteroccurences
Configure billing mode
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
.
Differences between classic and flexible billing mode
Credit proration calculations
Credit prorations are issued when customers downgrade their subscriptions or cancel subscription items before the end of their billing period. 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, 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 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 canceling 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. |
Usage-based pricing
Suppress zero-amount line items when adding usage-based items
Flexible billing mode doesn’t create zero-amount line items when you add usage-based items to a subscription. If the invoice is empty as a result, we don’t generate one.
For example, when adding a monthly usage-based item during subscription creation or update:
Classic | Flexible |
---|---|
A 0 USD line item is generated on the invoice for the usage-based item. This also applies when updating a subscription without cycling to add a usage-based item while using proration_ . | A 0 USD line item isn’t added to the invoice for the usage-based item. If the resulting invoice wouldn’t contain any items, we don’t generate one. |
Bill usage-based items 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 January 5: 1000 API calls at 0.1 USD per 100 calls (Price A).
- Price change on January 15: the price changes to 0.15 USD per 100 calls (Price B).
- Usage on January 20: 500 API calls.
Classic | Flexible |
---|---|
Stripe only bills for the usage that was reported since changing to the current price.
Total invoice amount = 0.75 USD. | Stripe bills for all usage in the current period at the price effective at the time it’s reported.
Total invoice amount = 1.75 USD. |
Bill for unbilled usage when removing usage-based items
Flexible billing mode generates an invoice item for unbilled usage when removing a usage-based 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 usage-based subscription item. | An invoice item is generated for unbilled usage when removing a usage-based subscription item. |
Reset the billing cycle anchor
Flexible billing mode only resets your billing cycle anchor on subscription updates when you explicitly set billing_
to a value other than unchanged
.
Classic | Flexible |
---|---|
The billing_ 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_ is never automatically reset. |
Consolidated invoicing for subscription schedule phase transitions with usage-based items
Flexible billing mode consistently generates a single invoice when a subscription cycles. This change eliminates separate invoices for removed usage-based items and improves billing consistency.
When your subscription with usage-based items transitions between phases:
Classic | Flexible |
---|---|
Two invoices are generated. | A single consolidated invoice is generated. This invoice includes both usage-based and licensed items, applies discounts from the previous phase to usage-based billing, and uses tax rates from the next phase. |
Scheduled subscription cancellation
You can disable prorations for a truncated first subscription period (when setting cancel_
on creation) using the proration_
parameter.
Classic | Flexible |
---|---|
Prorations are applied to the first subscription period. | Prorations aren’t applied to the first subscription period. |
Backdate subscriptions
When 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_
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 (March 1 - March 31):
- Usage reported: 100 GB of storage used.
- Price: 10 USD per 10 GB.
Billing Period 2 (April 1 - April 30):
- 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: March 1 to April 30.
Classic | Flexible |
---|---|
Charges for the entire backdated period are calculated collectively as a single line item. Total charges:
| Backdated time ranges are split into multiple invoice line items according to subscription period boundaries. Total charges:
|
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 January 1st to February 1st
- Normal billing period from February 1st to March 1st
- Trial period from March 1st to April 1st
Classic | Flexible |
---|---|
The subscription. always refers to the first trial a subscription started. | The subscription. 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_
if you modify the cancel_
date.
Classic | Flexible |
---|---|
If trial_ date is later than cancel_ , trial_ is set to the cancellation date. If cancel_ is later updated or removed, trial_ isn’t set to its original value. | Scheduling a subscription cancellation using cancel_ no longer alters the trial_ date. This ensures that trials run for their intended duration regardless of cancellation date updates. |
Standardize trial period line item description
Flexible billing mode uses a consistent description format for both usage-based and licensed items during trial periods.
For example, when you have a monthly coffee subscription (licensed) and alpaca_
subscription (usage-based), the subscription description displays as following:
Classic | Flexible |
---|---|
Licensed items use the template
| The same format,
|
Re-bill 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 trialing item price_
to a trialing subscription with price_
:
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 of 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_
.
Classic | Flexible |
---|---|
Billing cycle anchor reset invoices include pending items, while always_ 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. |