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
Field
Type
Description
idrequired
string · path
The organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequired
string · path
The workspace's id (`ws_…`).
Idempotency-Key
string · header
Any 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
Field
Type
Description
cap_cents
integer
Its 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
Field
Type
Description
objectrequired
enumshared_plan_workspace
—
workspace_idrequired
string
`ws_…`
external_idrequired
string
Your own id for it, if you gave one.
namerequired
string
—
cap_centsrequired
integer
What it may draw from the shared plan each period, allowance and overage together. Null: no cap.
joined_atrequired
string
—
used_centsrequired
integer
What it drew this period, counted against its cap.