Change the org's active Pro subscription to another Pro plan: a named package (e.g. mighty/super/ultra) or a custom plan given as explicit machine/storage/credit tiers. This is the one endpoint for every Pro → Pro change (named ↔ named, named ↔ custom, custom ↔ custom). Diffs the target's machine, storage, credit, and base-platform-fee line items against the current subscription and applies them as one or two atomic Stripe updates: the machine/storage/fee items (adding, swapping, or removing — including the vellum_pro_base fee) settle in a first Subscription.modify that bills immediately, while any included-credit bundle change settles in a separate proration_behavior=none modify. A credit-tier INCREASE additionally charges the flat price difference between the two bundles immediately and grants the credit difference immediately (mirroring change-credit-tier); when that difference cannot be charged (active discount, no chargeable payment method, or a declined charge) the credits simply apply at the next cycle and the package switch stands. Credit decreases settle at the next cycle. A net price increase on the primary items invoices immediately and gates on payment success (HTTP 402 on a declined card, leaving the plan unchanged); a net decrease nets onto the next invoice. Machines above the new package's ceiling are capped via vembda and lower ceilings grow asynchronously; PVCs are never shrunk. Rejected with HTTP 409 while a cancellation is pending. A named package is gated on the pro-packages flag (an unknown or gated package returns the same HTTP 400); a custom target is not gated, like the per-dimension tier endpoints it replaces. A custom plan ALWAYS carries the base platform fee and clears the package pin (package is null in the response); only the Mighty package is sold without the fee, so leaving Mighty for any other plan adds the fee (invoiced immediately with the rest of the net increase) and grants the fee-backed managed-email / phone-number entitlements, while moving to Mighty removes it. Custom targets follow the per-dimension rules: storage is upgrade-or-keep, and retired credit bundles / legacy storage tiers are rejected unless unchanged.
Request
- The document declares no server URL.
- Auth: one of:
- API key in cookie sessionid
- API key in header X-Session-Token
Headers
Required if using Cookie-based or X-Session-Token authentication methods.
Request body
Response
Changes
- ▲
the request's body type changed from
objectto no type (media type: application/json) - ▲
the response property
became nullable for the status - ▲
the
response's property type changed fromobjectto no type for status - ▲
removed the required property
/from the response with the status - ▲
removed the required property
/from the response with the status - ▲
removed the required property
/from the response with the status - ▲
removed the required property
/from the response with the status - ●
removed the request property
(media type: application/json) - ●
removed the request property
(media type: application/x-www-form-urlencoded) - ●
removed the request property
(media type: multipart/form-data) - ○
added to the request body
oneOflist (media type: application/json) - ○
added to the request body
oneOflist (media type: application/x-www-form-urlencoded) - ○
added to the request body
oneOflist (media type: multipart/form-data) - ○
the request's body type was generalized from
objectto no type (media type: application/x-www-form-urlencoded) - ○
the request's body type was generalized from
objectto no type (media type: multipart/form-data) - ○
added to the
response propertyallOflist for the response status
- ▲
- ○
added the optional property
to the response with the status - ○
added the optional property
to the response with the status
- ○