Enable increased flexibility for subscriptions

Flexible billing mode provides accurate and predictable billing behavior and additional features for managing subscriptions. Setting billing_mode=flexible on a subscription changes how Subscription objects behave throughout their lifecycle and in response to upgrades, downgrades, and cancellations.

Flexible 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
• Prebilling Private preview
• The use of the legacy max_occurences parameter

Configure billing mode

Create a new subscription with flexible billing mode

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
$stripe = new \Stripe\StripeClient([
  'api_key' => 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2',
  'stripe_version' => '2025-06-30.basil',
]);

$subscription = $stripe->subscriptions->create([
  'items' => [['price' => 
'{{PRICE_ID}}']],
  'customer' => 
'{{CUSTOMER_ID}}',
  'billing_mode' => ['type' => 'flexible'],
  'payment_behavior' => 'default_incomplete',
  'payment_settings' => ['save_default_payment_method' => 'on_subscription'],
]);

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "billing_mode": {
    "type": "flexible",
    "updated_at": 1751071020
  },
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,

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.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
$stripe = new \Stripe\StripeClient(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2');

$subscription = $stripe->subscriptions->migrate(
  'sub_123',
  ['billing_mode' => ['type' => 'flexible']]
);

{
  "id": "sub_123",
  "billing_mode": "flexible",
  "billing_mode_details": {
    "updated_at": 1716883200 // Example timestamp
  },
  // ... other subscription details
}

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, make sure it matches the existing subscription or create a new subscription.

Differences between classic and flexible billing mode

The following sections describe how various subscription behaviors differ between the classic and flexible billing modes.

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.

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.

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:

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 (Price A)
• Price change on January 15: the price changes to 0.15 USD (Price B)
• Usage on January 20: 500 API calls

Bill for unbilled usage when removing usage-based items

Depending on the value of proration_behavior, flexible billing mode might generate 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 that occur mid-period. For phase transitions that coincide with any subscription item current_period_end, an invoice gets created with an invoice line item for the removed 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_cycle_anchor to a value other than unchanged.

Consolidated invoicing for subscription schedule phase transitions with usage-based items

Flexible billing mode consistently generates a single invoice when a subscription renews. This change eliminates separate invoices for removed usage-based items and improves billing consistency.

When your subscription with usage-based items transitions between phases:

Scheduled subscription cancellation

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

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_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 periods. 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.

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

Preserve original trial end date when subscription cancels

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

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_ai_tokens subscription (usage-based), the subscription description displays as following:

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_b to a trialing subscription with price_a:

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.

Mixed intervals on the same subscription

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.