organizations

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.

post/v1/organizations/billing/subscription/change-package/

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in cookie sessionid
    • API key in header X-Session-Token

Headers

Vellum-Organization-Idstring uuid

Required if using Cookie-based or X-Session-Token authentication methods.

Request body

OR

Response

status'ok' | 'no_op' required
  • ok - ok
  • no_op - no_op
credit_charged_usdstring nullable
credit_granted_usdstring nullable

Changes

    • ▲

      the request's body type changed from object to no type (media type: application/json)

    • ▲

      the response property became nullable for the status

    • ▲

      the response's property type changed from object to 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 oneOf list (media type: application/json)

    • ○

      added to the request body oneOf list (media type: application/x-www-form-urlencoded)

    • ○

      added to the request body oneOf list (media type: multipart/form-data)

    • ○

      the request's body type was generalized from object to no type (media type: application/x-www-form-urlencoded)

    • ○

      the request's body type was generalized from object to no type (media type: multipart/form-data)

    • ○

      added to the response property allOf list for the response status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status