Add a workspace to the shared plan

Add a workspace to the shared plan

PUT/api/v1/organizations/{id}/shared-plan/workspaces/{workspace_id}

PUT /organizations/{id}/shared-plan/workspaces/{workspace_id}
curl -X PUT 'https://www.unitpost.com/api/v1/organizations/org_123/shared-plan/workspaces/ws_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "shared_plan_workspace",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "name": "Example",
  "cap_cents": 0,
  "joined_at": "2026-01-01T00:00:00.000Z",
  "used_cents": 0
}

Put one of the organization's workspaces on the shared plan, with an optional cap_cents (left out: no cap). It moves onto the organization's card (one more workspace on its billing) and draws on the shared allowance from now; its own usage this period so far stays its own. Already on it: cap_cents, when sent, sets its cap, and nothing else changes. Refused with the reason in details[0].code: not_approved (403: the shared plan isn't turned on), no_plan or plan_inactive (none bought, not active, or set to end), own_plan (it pays for a plan of its own: set that to end first), grant (a plan Unitpost's team gave it), payer_change (a change of who pays is scheduled), suspended, closed, already_member (on another shared plan) or limit_reached (the plan covers no more workspaces, or the organization's card is at its workspace limit), all 409 but the first. Idempotency-Key is optional: a retry with it answers what the first call did. The workspace's activity log names the key. The key's creator must still be an organization Owner. Takes an organization key (ok_live_…) with organizations:billing.

Parameters3 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body1 field
FieldTypeDescription
cap_centsintegerIts cap, in cents a period (0 stops it drawing, null: none). Left out: none on a join, unchanged when it is already on the plan.
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredenumshared_plan_workspace—
workspace_idrequiredstring`ws_…`
external_idrequiredstringYour own id for it, if you gave one.
namerequiredstring—
cap_centsrequiredintegerWhat it may draw from the shared plan each period, allowance and overage together. Null: no cap.
joined_atrequiredstring—
used_centsrequiredintegerWhat it drew this period, counted against its cap.
200400401403404409422429

Search docs and guides

Search the docs and product guides.