Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Overview
Online payments
Products and prices
Invoicing
Subscriptions
    Overview
    How subscriptions work
    Recurring pricing models
    Get started
    Quickstart
    Integrate a SaaS business
    Embed a pricing table
    Design an integration
    Build a subscriptions integration
    Migrate subscriptions to Stripe
    Billing resources
    Coupons
    Customers
    Subscriptions
    Subscription invoices
    Manage subscriptions
    Change subscriptions
      Upgrade and downgrade subscriptions
      Cancel subscriptions
      Manage prorations
      Pause payment collection
      Share an update payment details link
      Manage pending updates
      Set billing cycles
      Customer credit balance
    Usage-based billing
    Use trial periods
    Set payment methods
    Subscriptions with multiple products
    Set subscription quantities
    Subscription webhooks
    Schedule subscriptions
    Tax
    Sales-led B2B billing
    Integrate with Salesforce
    Manage recurring revenue
    Revenue recognition
    Revenue recovery
    Subscription metrics
    Customer management
    Overview
    Set up the the no-code customer portal
    Set up the customer portal with the API
    Configure the customer portal
    Testing
    Test your integration
    Test clocks
    Strong Customer Authentication (SCA)
    Invoices API updates
Quotes
In-person payments
Multiparty payments
After the payment
Add payment methods
Payment Links
Stripe Checkout
Stripe Elements
About the APIs
Regulation support
Implementation guides
Testing
Billing
·
HomePaymentsSubscriptionsChange subscriptions

Prorations

Learn about prorations.

Changes to a subscription such as upgrading or downgrading can result in prorated charges. For example, if a customer upgrades from a 10 USD per month subscription 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.

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 are created only for licensed (per-seat) subscriptions because they’re billed at the start of each billing period.

Preview a proration

You can retrieve an upcoming invoice to preview changes to a subscription. This API call doesn’t modify the subscription, 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.

# 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_4eC39HqLyjWDarjtT1zdp7dc'
# 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.upcoming({ customer: 'cus_4fdAW5ftNQow1a', subscription: 'sub_49ty4767H20z6a', subscription_items: items, subscription_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.
{ "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, "billing_reason": "upcoming",

You can use this information to confirm the changes with the customer before modifying the subscription. Because Stripe prorates to the second, prorated amounts can 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, you can pass the same date using the proration_date parameter on a subscription so that the proration is calculated at the same time.

# 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_4eC39HqLyjWDarjtT1zdp7dc'
subscription = Stripe::Subscription.update( 'sub_49ty4767H20z6a', { items: [ { id: subscription.items.data[0].id, price: 'price_CBb6IXqvTLXp3f', }, ], proration_date: proration_date, } )

Disable prorations

Prorating is controlled by the proration_behavior parameter and defaults to create_prorations.

You can disable prorations on a per-request basis by setting the proration_behavior parameter to none. There is no parameter that turns off all future prorations for a Subscription. If you want to disable prorations indefinitely, you need to set proration_behavior to none for every request that generates prorations:

Command Line
curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -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?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Preview a proration
Disable prorations
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$