Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Customers
Products and Prices
Tax Rates
Customer portal
Quotes
Start with a use case
Subscriptions with Checkout
Fixed-price subscriptions with Elements
Metered billing with Elements
Per-seat billing with Elements
Manage subscriptions
How subscriptions work
Subscription webhooks
Change subscriptions
Strong Customer Authentication (SCA)
Improved tax support
Invoices API updates
Migrating to Prices
Additional features
Adding taxes
Applying discounts
Backdating subscriptions
Decimal amounts
Metered billing
Multiple subscriptions
Prorations
Setting quantities
Subscriptions with Connect
Subscriptions with multiple products
Subscription schedules
Tiered pricing
Quantity transformation
Using trial periods
Testing
Add payment methods
Bacs Direct Debit in the UK
BECS Direct Debit in Australia
SEPA Direct Debit in the EU
Invoice customers
How invoices work
Create an invoice
Customize invoices
Hosted invoice page
Additional features
Revenue recognition
Overview
Reports
Methodology
Examples
Overrides
Testing
billing
·
HomePaymentsSubscriptions and invoicesAdditional features

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/account/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/account/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 the default behavior, but you can disable it by setting proration_behavior to none:

Terminal
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?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Preview a proration
Disable prorations