Quote or apply a plan upgrade

Move the workspace owner subscription to a strictly higher plan (tier). Never moves down; use the downgrade endpoint for that. Always quote first: send dry_run: true to get the exact prorated charge for today, the new recurring price and interval, and the new account limit and credits, without charging anything. Then send the same body without dry_run to apply it. Applying charges the saved card the prorated difference right away, at the same billing interval. With a working card the plan changes immediately (status: applied). If the card needs 3D Secure or is declined, NOTHING changes: the response is 200 with status: payment_required and a Stripe-hosted hosted_invoice_url for the owner to complete, and the plan changes automatically when that invoice is paid. Until then further changes are refused with 409 payment_pending. A trialing subscription keeps its trial: the price changes and nothing is charged today. The billing interval does not change in an upgrade. The one exception is Agency, which is monthly or yearly only: from a weekly plan, send interval as month or year (otherwise 409 interval_unavailable); any other interval change is 409 interval_change_unsupported. Refused with 409 and a billing_url to finish on the billing page: a subscription that includes the API and MCP add-on (api_addon_requires_dashboard); any discount other than a permanent percent-off below 100 (discount_requires_dashboard); a subscription schedule (schedule_attached); and an account without a card subscription (no_subscription). A standalone API and MCP add-on that would stop granting access on the target plan (Agency needs the Agency add-on) is also api_addon_requires_dashboard, but the response carries an api_addon_url pointing to the API page, where the add-on is switched. request_id (8 to 64 letters, digits, _ or -) makes a retry safe: nothing is charged twice. A retry after the first attempt landed is refused (not_an_upgrade or quote_stale), not replayed. Leave it out to have one generated; a malformed one is 400 invalid_request_id. Use a fresh one for each attempt. expected_current_tier and expected_interval (optional) pin the quote you showed: if either changed since, nothing is charged and the answer is 409 quote_stale. Workspace owner only (403 workspace_owner_required for teammates, even with an owner-issued key). Requires the billing:write scope. Bypasses the API add-on paywall.