Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Billing
    Overview
    About the Billing APIs
    Subscriptions
      Overview
      Quickstart
      Use cases
      Build your integration
      Subscription features
        Subscription invoices
        Subscription schedules
        Subscription pricing
        Recurring pricing models
        Embed a pricing table
        Start subscriptions
        Set quantities
        Set billing cycles
        Backdate subscriptions
        Subscribe to multiple items
        Set trial periods
        Apply coupons
        Migrate subscriptions to Stripe
        How credit prorations are calculated
        Subscription payments
        Subscription payment methods
        Integrate with third-party payment processing
        Collection methods
        Share a link to update payment details
        Strong Customer Authentication (SCA)
        Manage subscriptions
        Modify subscriptions
        Manage pending updates
      Analytics
    Invoicing
    Usage-based billing
    Connect and Billing
    Tax and Billing
    Quotes
    Revenue recovery
    Automations
    Scripts
    Revenue recognition
    Customer management
    Entitlements
    Test your integration
Tax
Reporting
Data
Startup incorporation
HomeFinance automationBillingSubscriptionsSubscription features

Enable flexible behavior for subscriptions

Use billing mode to control how prorations and invoices for subscriptions are calculated and orchestrated.

Copy page

Subscription prorations

Read our prorations guide to learn how to manage prorations for modified subscriptions and understand their behavior.

Currently, credit proration amounts are calculated based on the value of the subscription item’s current price, tax, quantity, and the last discounts used.

You can configure billing_mode=flexible to enable a different proration logic that calculates credit prorations based on the original amount previously debited to a customer.

Public preview

To enable the new proration calculation logic by configuring billing_mode=flexible, you must upgrade your API version to to 2025-04-30.preview or later.

The current behavior could lead to unexpected prorations when a customer’s tax rates change, debit prorations are disabled, or complex amounts off coupons are used. The improved proration logic calculates credit prorations based only on the original amount previously debited to a customer. When a customer makes a change to their subscription that results in a credit, the proration is calculated using the amount they were previously billed, regardless of subsequent changes made to the subscription. Stripe recommends using billing_mode=flexible if the limitations of the public preview don’t apply to you.

Public preview limitations Public preview

During public preview, billing_mode=flexible isn’t compatible with all of Stripe Billing’s functionality.

When billing_mode=flexible is configured:

  • Subscription Schedules are not supported.
  • Usage-based billing is not supported.
  • Automatic tax calculation is not supported.
  • Trials are not supported.
  • Quotes endpoints are not supported.
  • You can’t reset the billing cycle anchor.
  • You can’t create backdated subscriptions.
  • You can’t pause payment collection on subscriptions.

If you use these features with billing_mode=flexible, they return a 400 error code.

Configure billing mode Public preview

You can configure billing_mode=flexible on specific subscriptions, and you can have multiple subscriptions with different billing_mode configurations. You can’t change the billing _mode after you set it (this ensures consistent logic and behavior throughout the lifecycle of each subscription).

When you configure billing_mode=flexible, it also updates subscription.trial_start to reflect the most recent trial start date.

Specify flexible in the billing_mode parameter on any API request that creates a subscription:

  • Subscriptions
  • Invoice previews
  • Checkout Sessions

Calculation logic with no prorations

In the following scenario, a 10 USD monthly subscription is upgraded to 20 USD with proration_behavior set to none for 10 days. There is no previous debit to base it on. Later, the subscription is downgraded to 10 USD a month with proration_behavior set to always_invoice.

To set up this scenario, first you create a subscription for 10 USD/month on 2025-04-01:

Command Line
cURL
curl https://api.stripe.com/v1/subscriptions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][price]"=price_10_monthly

The response includes the invoice that’s created for this subscription:

Create subscription response
{ id: "sub_123", latest_invoice: { id: "in_123", total: 10_00, currency: "usd" } }

Then, on 2025-04-11, you upgrade the subscription to 20 USD/month without creating prorations:

Command Line
cURL
curl https://api.stripe.com/v1/subscriptions/sub_123 \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][price]"=price_20_monthly \ -d proration_behavior=none

You can see that the latest invoice is unchanged because proration_behavior is none:

Upgrade subscription response
{ id: "sub_123", latest_invoice: { id: "in_123" } }

Finally, on 2025-04-21, you downgrade the subscription to 10 USD/month and create prorations:

Command Line
cURL
curl https://api.stripe.com/v1/subscriptions/sub_123 \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][price]"=price_10_monthly \ -d proration_behavior=always_invoice

The default proration calculation logic creates a credit proration based on the current price, even though the customer never paid the 20 USD/month rate. The latest invoice credits a third of the month for 20 USD (-6.67 USD), even though the customer never paid for the price_20_monthly price. It also debits a third of the month for 10 USD (3.33 USD).

The calculation logic enabled with billing_mode=flexible creates a credit proration based on the last price billed for the subscription item. In this case, the latest invoice credits a third of a month for the 10 USD/month price billed on 2025-04-01 (3.33 USD) and debits a third of the month for the 10 USD price (3.33 USD). The credit and debit cancel out so the invoice total is 0 USD.

Before
After
# Default behavior # billing_mode = classic { id: "sub_123", latest_invoice: { id: "in_456", total: -3_34, currency: "usd" } }
# New behavior # billing_mode=flexible { id: "sub_123", latest_invoice: { id: "in_456", total: 0, currency: "usd" } }

Calculation logic for coupons applied to multiple subscription items

The amount_off coupon on the credit proration is weighted to prevent overbilling.

In the following scenario, a 5 USD coupon is unevenly allocated to a 25 USD monthly subscription for a 10 USD item and 20 USD item.

To set up this scenario, you create a subscription with multiple items and a coupon on 2025-02-01:

Command Line
cURL
curl https://api.stripe.com/v1/subscriptions \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][price]"=price_20_monthly \ -d "discounts[0][coupon]"=five_dollars_off

Which returns this response:

Create subscription with multiple items and a coupon response
{ id: "sub_123", latest_invoice: { id: "in_123", total: 25_00, currency: "usd", lines: { data: [ { id: "ili_1", amount: 10_00, price: "price_10_monthly", discount_amounts: [{ discount: "di_a", amount: 1_66 }] }, { id: "ili_2", amount: 20_00, price: "price_20_monthly", discount_amounts: [{ discount: "di_a", amount: 3_34 }] }, ] } } }

To cancel the 10 USD/month subscription item using billing_mode=classic:

Command Line
cURL
curl https://api.stripe.com/v1/subscription_items/si_10_monthly \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d proration_behavior=create_prorations

To cancel the same item using billing_mode=flexible:

Command Line
cURL
curl https://api.stripe.com/v1/subscription_items/si_10_monthly \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d proration_behavior=create_prorations \ -d billing_mode=flexible

The default behavior distributes a 5 USD coupon to each item (2.5 USD each), cancelling the cheaper item (5 USD) and resulting in a refund of 2.5 USD. The total has been calculated with the formula -0.5 x (10 USD price - 5 USD coupon) = -2.50 USD

The new behavior reflects the proportional discount applied to the canceled item, rather than potentially applying the full discount amount to the proration calculation. The total has been calculated using the formula -0.5 x (10 USD price - 1.66 USD discount amount) = -4.17 USD.

Before
After
# Default behavior # billing_mode = classic { "id": "sub_123", "latest_invoice": { "id": "in_456", "total": -250, "currency": "usd" } }
# New behavior # billing_mode = flexible { "id": "sub_123", "latest_invoice": { "id": "in_789", "total": -417, "currency": "usd" } }
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc