Deep explanation of Stripe proration with real upgrade and downgrade calculation examples, behavior modes, and common gotchas.
When a customer changes plans mid-cycle, Stripe calculates proration by: (1) Crediting the unused portion of the old plan, and (2) Charging for the remaining days on the new plan. Example: Customer on $99/mo Pro plan upgrades to $249/mo Team plan on day 12 of a 30-day cycle. Credit for unused old plan: $99 × (18/30) = $59.40 credit. Charge for remaining new plan: $249 × (18/30) = $149.40 charge. Net prorated amount: $149.40 - $59.40 = $90.00 charged today.
Downgrades work the same math but in reverse. Customer on $249/mo Team downgrades to $99/mo Pro on day 12. Credit for unused Team: $249 × (18/30) = $149.40 credit. Charge for remaining Pro: $99 × (18/30) = $59.40. Net: $90.00 credit applied to the next invoice. Stripe doesn't refund downgrade credits by default — they reduce the next invoice amount. If the credit exceeds the next bill, it rolls forward.
Stripe offers three modes via the API's proration_behavior parameter: create_prorations (default) — calculates prorated line items, charges at next invoice. always_invoice — creates and pays a new invoice immediately for upgrades. none — no proration, customer pays the new price starting next billing cycle. For upgrades, most SaaS companies use always_invoice to collect revenue immediately. For downgrades, create_prorations avoids issuing refunds.
After a plan change, the next invoice contains line items showing the math: a negative line for the credit ('Unused time on Pro') and a positive line for the charge ('Remaining time on Team'). Go to the customer's Invoices tab to see these. Understanding these line items helps you explain billing to confused customers — proration questions are among the top support tickets for SaaS companies.
Stripe prorates by the second, not the day, so mid-day changes are precise. Annual to monthly switches: Stripe prorates based on the daily rate of the annual plan ($1,188/year = $3.25/day). Quantity changes (adding seats): same logic applies per seat. Coupons: proration uses the discounted price, not the list price. Trial periods: no proration during trials since no payment has been made.
In the Dashboard, when you click Update subscription, Stripe shows a preview of the prorated amount before you confirm. Via the API, use the upcoming invoice endpoint to preview what the customer will be charged. Always preview for high-value plan changes — a surprised customer is an unhappy customer.
Install Coby on Stripe and ask anything — like a teammate who never sleeps.
Install Coby on your Stripe account in 30 seconds. Free to start, no credit card required.