Proration for Plan Changes
Calculating the proportional credit or charge when a customer upgrades or downgrades their subscription plan mid-billing cycle, ensuring fair billing for the time spent on each plan.
Description
Proration calculates the fair adjustment when a customer changes their subscription plan partway through a billing cycle. If a customer upgrades from a $10/month plan to a $20/month plan on day 15 of a 30-day billing cycle, proration credits them for the unused 15 days on the old plan (-$5) and charges for the remaining 15 days on the new plan (+$10), resulting in a net charge of $5. Stripe handles proration automatically when you update a subscription's price, creating credit and debit invoice line items that reflect the time-proportional adjustments.
Stripe's proration_behavior parameter on stripe.subscriptions.update() controls how prorations are handled. The options are create_prorations (default, calculates and applies proration credits/debits), always_invoice (creates prorations and immediately invoices the customer), and none (no proration, the new price takes effect at the next billing cycle). For upgrades, always_invoice is typically preferred so the customer is charged immediately. For downgrades, create_prorations defers the credit to the next billing cycle, reducing the next invoice amount.
Previewing prorations before the customer confirms the change is essential for transparency. Use stripe.invoices.upcoming({ customer, subscription, subscription_items: [{ id: si_id, price: new_price_id }], subscription_proration_date }) to generate a preview of the proration amounts. Display the prorated credit for unused time on the current plan, the prorated charge for the new plan, and the net amount the customer will pay today (for immediate invoicing) or the adjusted next invoice amount (for deferred proration). This preview should be shown in your plan change confirmation UI before executing the update.
Prompt Snippet
Preview proration amounts before confirming a plan change using stripe.invoices.upcoming({ customer: cus_id, subscription: sub_id, subscription_items: [{ id: si_id, price: new_price_id }], subscription_proration_date: Math.floor(Date.now() / 1000) }) and display the prorated credit/debit line items to the customer in the confirmation modal. Execute the plan change with stripe.subscriptions.update(sub_id, { items: [{ id: si_id, price: new_price_id }], proration_behavior: 'always_invoice' }) for upgrades to charge immediately, and proration_behavior: 'create_prorations' for downgrades to credit the next invoice. Handle the invoice.paid webhook after the proration invoice to confirm the upgrade was paid and activate the new plan's features.Tags
Related Terms
Subscription Billing (Stripe)
Managing recurring payment cycles using Stripe's Subscription and Price APIs, including plan creation, billing intervals, upgrades/downgrades, and lifecycle event handling.
Invoice Generation
Creating and managing invoices for one-time charges and subscription billing cycles, including line item customization, tax itemization, and PDF generation through Stripe's Invoice API.
Customer Portal
A Stripe-hosted or custom-built self-service interface where customers can manage their subscriptions, update payment methods, view invoices, and handle billing-related actions without contacting support.
Coupon/Discount System
Implementing promotional pricing through Stripe's Coupon and Promotion Code APIs, supporting percentage and fixed-amount discounts with configurable duration, redemption limits, and eligibility rules.