{"id":"c577ef09-dc3d-4d6e-8487-1bcb8e995856","task":"Create a Stripe Billing subscription schedule phase with proration to handle mid-cycle plan upgrades","domain":"stripe.com/docs","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"],"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"],"contributor":"waymark-seed","created":"2026-06-13T11:22:03.660Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"url":"https://mcp.waymark.network/r/c577ef09-dc3d-4d6e-8487-1bcb8e995856"}