Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
    Overview
    How subscriptions work
    Get started
    Quickstart
    Plan an integration
    Build an integration
    Use cases
    About subscriptions
    Enable billing mode
    Subscription event definitions
    Entitlements
    Subscription invoices
    Subscription schedules
    Recurring pricing models
    Strong Customer Authentication (SCA)
    Set up subscriptions
    Configure collection methods
    Embed a pricing table
    Set quantities
    Set billing cycles
    Manage subscriptions
    Migrate subscriptions to Stripe
    Subscribe to multiple items
    Backdate subscriptions
    Set trial periods
    Handle subscriptions with deferred payment
    Apply coupons
    Modify subscriptions
      Change prices
      Cancel subscriptions
      Pause payment collection
      Manage prorations
      Manage pending updates
    Manage subscription payment methods
    Analytics
Invoicing
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueSubscriptionsModify subscriptions

Prorations

Manage prorations for modified subscriptions.

The most complex aspect of changing existing subscriptions are prorations, where the customer is charged a percentage of a subscription’s cost to reflect partial use. This page explains how prorations work with subscriptions and how to manage prorations for your customers.

How prorations work

For example, upgrading or downgrading a subscription can result in prorated charges. If a customer upgrades from a 10 USD monthly plan to a 20 USD option, they’re charged prorated amounts for the time spent on each option. Assuming the change occurred halfway through the billing period, the customer is billed an additional 5 USD: -5 USD for unused time on the initial price, and 10 USD for the remaining time on the new price.

Proration ensures that customers are billed accurately, but a proration can result in different payment amounts than you might expect. Negative prorations aren’t automatically refunded and positive prorations aren’t immediately billed, although you can do both manually.

You can preview a proration to view the amount before applying the changes. To learn more about how credit prorations work, read our guide.

Prorations and discounts

Any adjustments from discounts are reflected in the proration invoice item’s amount. Additional discounts at the invoice item level or invoice line item level don’t apply to prorations because they have discountable=false.

This behavior is different from non-prorations, which show discount adjustments in discount_amounts.

What triggers prorations

By default, the following scenarios result in a proration:

  • Changing to a price with a different base cost
  • Changing to a price with a different billing interval
  • Adding a trial period to an active subscription
  • Changing the quantity
  • Licensed (per-seat) subscriptions (because they’re billed at the start of each billing period)

Manually creating your own prorations

To calculate your own prorations outside of Stripe and add them to the subscription, pass add_invoice_items with a negative unit_amount (equal to the calculated proration amount) to these endpoints:

  • CreateSubscription
  • UpdateSubscription
  • CreateSubscriptionSchedule
  • UpdateSubscriptionSchedule

When prorations are applied

Prorations only apply to charges that occur ahead of the billing cycle. Usage-based billing isn’t subject to proration.

The prorated amount is calculated as soon as the API updates the subscription. The current billing period’s start and end times are used to calculate the cost of the subscription before and after the change.

Prorations and unpaid invoices

Stripe calculates prorations based on the subscription’s state at the time of an update, assuming that any previous invoices for the subscription will eventually be paid. If a customer changes their subscription while having an unpaid invoice for the current period, they might receive a credit for unused time on the higher-priced plan, even if they haven’t paid for that time yet.

To avoid crediting for unpaid time, you can disable prorations when the subscription’s latest invoice is unpaid. When updating the subscription, set proration_behavior to none. Select one of the following approaches:

  1. To keep the original billing cycle: Manually create a one-off invoice for any new charges.
  2. To charge immediately for the new plan and reset the billing cycle: Set billing_cycle_anchor to now. For more details, see Reset the billing cycle to the current time.

Either of these approaches can lead to double payment if the customer eventually pays the old invoice. To avoid this, void the unpaid invoice.

Taxes and prorations

For information about how taxes work with prorations, see Collect taxes for recurring payments.

Credit prorations

Credit prorations are issued when customers downgrade their subscriptions or cancel subscription items before the end of their billing period. Stripe offers two approaches for calculating credit prorations, depending on whether you set your subscription’s billing_mode to classic or flexible.

Calculation logic with no prorations

In the following scenario, you upgrade a 10 USD monthly subscription to 20 USD with the proration_behavior set to none for 10 days. There’s no previous debit to base it on. Later, you downgrade the subscription to 10 USD per month with the proration_behavior set to always_invoice.

To set up this scenario, first you create a subscription for 10 USD per month on April 1:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
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 April 11, you upgrade the subscription to 20 USD per month without creating prorations:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions/sub_123 \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "items[0][price]"=price_20_monthly \ -d proration_behavior=none

The latest invoice remains unchanged because proration_behavior is none:

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

Finally, on April 21, you downgrade the subscription to 10 USD per month and create prorations:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
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
Classic Flexible
The billing_mode=classic proration calculation logic creates a credit proration based on the current price, even though the customer never paid the 20 USD monthly 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 monthly price billed on April 1 (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.
# billing_mode = classic { id: "sub_123", latest_invoice: { id: "in_456", total: -3_34, currency: "usd" } }
# billing_mode = flexible { id: "sub_123", latest_invoice: { id: "in_456", total: 0, currency: "usd" } }

Calculation logic for coupons applied to multiple subscription items

Stripe weights the amount_off coupon on the credit proration to prevent over-billing.

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 February 1:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
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 monthly subscription item using billing_mode=classic:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
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
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_items/si_10_monthly \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d proration_behavior=create_prorations \ -d billing_mode=flexible
Classic Flexible
The default behavior distributes a 5 USD coupon to each item (2.5 USD each), canceling the cheaper item (5 USD) and resulting in a refund of 2.5 USD. Stripe calculates the total with the formula -0.5 x (10 USD price - 5 USD coupon) = -2.50 USD.The flexible behavior reflects the proportional discount applied to the canceled item, rather than potentially applying the full discount amount to the proration calculation. Stripe calculates the total using the formula -0.5 x (10 USD price - 1.66 USD discount amount) = -4.17 USD.
# billing_mode = classic { "id": "sub_123", "latest_invoice": { "id": "in_456", "total": -250, "currency": "usd" } }
# billing_mode = flexible { "id": "sub_123", "latest_invoice": { "id": "in_789", "total": -417, "currency": "usd" } }

Preview a proration

You can create a preview invoice to preview changes to a subscription. This API call doesn’t modify the subscription. Instead, it returns the upcoming invoice based only on the parameters that you pass. Changing the price or quantity both result in a proration. This example changes the price and sets a date for the proration.

Ruby
Python
PHP
Java
Node
Go
.NET
No results
# Set your secret key. Remember to switch to your live secret key in production. # See your keys here: https://dashboard.stripe.com/apikeys Stripe.api_key =
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
# Set proration date to this moment: proration_date = Time.now.to_i subscription = Stripe::Subscription.retrieve('sub_49ty4767H20z6a') # See what the next invoice would look like with a price switch # and proration set: items = [{ id: subscription.items.data[0].id, price: 'price_CBb6IXqvTLXp3f', # Switch to new price }] invoice = Stripe::Invoice.create_preview({ customer: 'cus_4fdAW5ftNQow1a', subscription: 'sub_49ty4767H20z6a', subscription_details: { items: items, proration_date: proration_date, } })

You can expand the example response below to see:

  • The credit for unused time at the previous price on lines 36-38.
  • The cost for time spent at the new price on lines 107-109.
  • The new subtotal and total for the invoice on lines 276-279.
{ "id": "upcoming_in_1OujwkClCIKljWvsq5v2ICAN", "account_country": "US", "account_name": "Test account", "amount_due": 3627, "amount_paid": 0, "amount_remaining": 3627, "application_fee_amount": null, "attempt_count": 0, "attempted": false,

Use this information to confirm the changes with the customer before modifying the subscription. Because Stripe prorates to the second, prorated amounts might change between the time they’re previewed and the time the update is made. To avoid this, pass in a subscription_proration_date to the invoice when you preview a change. When you update the subscription, pass the same date using the proration_date parameter on a subscription so that the proration is calculated at the same time.

Ruby
Python
PHP
Java
Node
Go
.NET
No results
# Set your secret key. Remember to switch to your live secret key in production. # See your keys here: https://dashboard.stripe.com/apikeys Stripe.api_key =
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
subscription = Stripe::Subscription.update( 'sub_49ty4767H20z6a', { items: [ { id: subscription.items.data[0].id, price: 'price_CBb6IXqvTLXp3f', }, ], proration_date: proration_date, } )

Control proration behavior

Prorating is controlled by the proration_behavior parameter, which has three possible parameter options: create_prorations, always_invoice, and none.

Default behavior

The default parameter for proration_behavior is create_prorations, which creates proration invoice items when applicable. These proration items are only invoiced immediately under certain conditions.

Create immediate prorations

To bill a customer immediately for a change to a subscription on the same billing cycle, set proration_behavior to always_invoice when you modify the subscription. This calculates the proration, then immediately generates an invoice.

Disable prorations

To disable prorations on a per-request basis, set the proration_behavior parameter to none. No parameter turns off all future prorations for a subscription. To disable prorations indefinitely, set proration_behavior to none for every request that generates prorations:

Command Line
curl
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
\ -d "items[0][id]"="si_1AkFf6LlRB0eXbMtRFjYiJ0J" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f" \ -d "proration_behavior"="none"

When prorations are disabled, customers are billed the full amount at the new price when the next invoice is generated.

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