Change the subscription plan

An upgrade charges the prorated price difference right away. The plan changes only once that invoice is paid; then the workspace gets the new plan's monthly credits minus the old plan's, once per change. status is upgraded when the payment went through, requires_action when the card needs authentication on hosted_invoice_url, and payment_failed when it was declined (the plan does not change). A downgrade (status scheduled_downgrade) is not prorated: there is no refund and no credits are taken back. The plan stays as it is until the next cycle, effective_at; then the lower price and credits start. Asking for the current plan while a downgrade is scheduled cancels the downgrade (status downgrade_canceled). An upgrade while a downgrade is scheduled is refused with status downgrade_scheduled (scheduled_plan and effective_at name the downgrade): cancel the downgrade first. While an upgrade payment is still pending, any change is refused with status payment_pending and hosted_invoice_url. While the plan is set to cancel in the billing portal, any change is refused with status cancel_scheduled, effective_at (the cancel date) and a message: resume the plan in the billing portal first. A subscription without automatic tax is refused with status tax_location_required and a message while the billing address cannot be used to add VAT: add it in the billing portal, then try again. Nothing is changed or charged on a refusal.

Scope: billing:manage. Acts on the account; keys bound to a customer are refused.