When a customer requests a plan change, use the Stripe Subscriptions preview invoice endpoint to show the customer the exact prorated amount they will be charged or credited before confirming.
Set the proration_behavior parameter on the subscription update: use 'create_prorations' to generate proration line items, 'none' to apply the new price only at the next renewal, or 'always_invoice' to immediately invoice the prorated difference.
For upgrades, the proration invoice is typically a positive amount charged immediately; for downgrades, it typically creates a credit applied to the next invoice.
After updating the subscription, retrieve the upcoming invoice to confirm the proration line items are as expected before presenting confirmation to the user.
Store the plan change event in your own database with the timestamp and previous plan details to support customer inquiries about unexpected charges.
Handle edge cases: proration when usage-based meters are active requires care — confirm the usage-based components are excluded from proration or reset as appropriate.
Known gotchas
If you update a subscription multiple times in the same billing period, proration credits and debits accumulate; the final invoice can be confusing for customers — preview the invoice before each change.
Proration amounts are calculated based on the exact second of the change; timezone handling in your UI matters because a change appearing to be at midnight may be calculated at a different time server-side.
Setting proration_behavior to 'none' on a downgrade means the customer continues to pay the higher price until renewal; clearly communicate this to avoid disputes.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?