POST /v1/subscriptions/{subscriptionId}/plan

Authentication

Send an API key as a bearer token. The key must carry the billing.payment.manage permission; a key without it is refused with 403, not 404.

This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/subscriptions/{subscriptionId}/plan \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "plan_version_id": <Uuid> }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Charges the prorated difference for the remainder of the current period, moves every site the subscription entitles, and supersedes the subscription onto the new plan version — keeping the existing period window, so the customer's renewal date does not move and they are not handed a free extra period. ⛔ A plan change SUPERSEDES rather than mutates, because a subscription pins the exact version it was sold so that a later catalogue edit cannot rewrite what a live subscriber pays. subscription_id in the response is therefore a new id and a client holding the old one must replace it. ⭐⭐ slots_before and slots_after are read back from the subscription rows, not derived from the plan that was asked for. A plan change that answers 200 and silently does not take effect is the worst outcome on this path, and a status code cannot tell that apart from one that worked. Mid-period money. A larger plan is charged the difference now — the customer asked for more room today, and applying it at the next renewal is the buy-flow dead end in another costume. A smaller plan returns the unused difference as account credit, not a card refund: it is instant, it cannot be unavailable, it is idempotent, and it is spendable on their next order. ⛔ Account credit carries no VAT credit note; a proration credit spans the current period's invoice rather than reversing it. ⛔ expected_total_minor is a money guard, not a convenience. It is the figure the customer was actually shown, and the change is refused 422 when the freshly-computed quote differs. Every other refusal is 422 as well, with nothing charged and nothing changed: a plan on another product line, the plan they are already on, a plan that has been re-priced since the page loaded, account usage above what a smaller plan allows, a card decline. ⛔ The downgrade guard is account-wide and there is no override. The same check_downgrade the site endpoint and the staff tariff endpoint call: sites, mailboxes, mailbox storage and disk across the org's subtree. Staff have an audited override because they sometimes genuinely need to move an over-limit account; a customer overriding their own quota check is not an override, it is no check. Repeating an identical request is the recovery and it is safe. Every step is idempotent on a key anchored to the subscription being left, so an attempt that died part-way is finished rather than duplicated: one order, one charge, one credit, one supersede. 404 for a subscription in another tenant as well as for one that does not exist. 503 when the driver behind an entitled site cannot move a package between types at all — our gap, not theirs. Requires billing.payment.manage — it charges a card, so the key that gates paying is the key that gates committing to a payment.

Parameters

Request body

Response

Errors this endpoint can return

401 · 403 · 404 · 422 · 429 · 503