Switch an existing subscription to another plan

Moves the workspace owner's EXISTING subscription to another plan, up or down, by modifying it in place. Does not create a second subscription and does not return a URL: the card is already on file, so the change applies immediately.

Prorated with create_prorations in both directions — the unused remainder of the old plan is credited and the used remainder of the new one charged, both on the NEXT invoice. No card is charged today. A DOWNGRADE takes effect at once, so an account holding more than the smaller plan includes is immediately over its ceiling; say so before the customer confirms.

enterprise is not a valid target and an enterprise account cannot be switched off this way — it is quoted and hand-provisioned. free is not a target either: ending a subscription is the cancel route, which keeps the paid plan until the period ends.

Same subject rules as checkout: the billing subject is the workspace OWNER on every lane, and a session-lane caller who is not the owner is refused 403.

The response reports what STRIPE accepted. plan on the billing summary is written by the customer.subscription.* webhook a moment later, so a summary fetched in the same breath may still report the old plan — render the value returned here and re-fetch the summary shortly after, rather than treating the lag as a failure.

Requires the billing:write scope. Accepts all three lanes: a session JWT (bounded by the caller's role on this workspace) or an il_* machine credential whose own scope set, workspace set and validity window cover it — both ceilings apply and neither can raise the other, so a credential carrying billing:write is still refused where the role does not permit it.

A credential with no scope record resolves to LEGACY_DEFAULT, which does NOT include billing:write — mint a key with it explicitly (POST /v2/workspaces/{id}/keys).