Create a Stripe Billing subscription schedule phase with proration to handle mid-cycle plan upgrades
domain: stripe.com/docs · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Retrieve the existing subscription and confirm its current_period_start and current_period_end
Call POST /v1/subscription_schedules with from_subscription set to the existing subscription ID to convert it to a scheduled subscription
Add a new phase to the schedule starting immediately with the upgraded plan price ID and set proration_behavior to create_prorations
Stripe calculates a proration credit for the unused portion of the current plan and a debit for the new plan; these appear as pending invoice items
Listen for the invoice.upcoming webhook to preview proration amounts and surface them to the customer before the upgrade is confirmed
Known gotchas
Proration items are created on the next invoice unless billing_cycle_anchor is reset; if you need an immediate prorated charge, set billing_cycle_anchor to now in the phase definition
Downgrading a plan mid-cycle with create_prorations generates a credit note against future invoices, not a refund; communicate this to customers expecting an immediate credit
Converting an existing subscription to a schedule is irreversible via the API; use release_subscription to detach from the schedule and return it to standard management if needed
Give your agent this knowledge — and 15,600+ 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?