---
title: "Add a workspace to the shared plan"
description: "Put one of the organization's workspaces on the shared plan, with an optional cap_cents (left out: no cap). `PUT /api/v1/organizations/{id}/shared-plan/workspaces/{workspace_id}`"
url: https://www.unitpost.com/docs/platform/put-organizations-id-shared-plan-workspaces-workspace-id
section: "Platform API reference"
updated: 2026-11-17
---
# Add a workspace to the shared plan

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

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`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The organization's id (`org_…`), from `GET /whoami` or Organization → API. |
| `workspace_id` | path | string | yes | The workspace's id (`ws_…`). |
| `Idempotency-Key` | header | string | no | 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 body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cap_cents` | integer | no | 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 fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | enum | yes | One of: `shared_plan_workspace`. |
| `workspace_id` | string | yes | `ws_…` |
| `external_id` | string | yes | Your own id for it, if you gave one. |
| `name` | string | yes | — |
| `cap_cents` | integer | yes | What it may draw from the shared plan each period, allowance and overage together. Null: no cap. |
| `joined_at` | string | yes | — |
| `used_cents` | integer | yes | What it drew this period, counted against its cap. |

## Responses

| Status | Description |
| --- | --- |
| 200 | The workspace on the shared plan. |
| 400 | An invalid `Idempotency-Key`, or a body that isn't JSON. |
| 401 | Missing or invalid organization key (a workspace key is refused). |
| 403 | API access not approved for the organization, no User-Agent, or `insufficient_scope`: the key lacks `organizations:billing` or its creator is no longer an organization Owner. Or `forbidden` with `details[0].code: "not_approved"`: the shared plan isn't turned on for the organization. |
| 404 | Not this key's organization, or not one of its workspaces. |
| 409 | `conflict` with `details[0].code`: `no_plan`, `plan_inactive`, `own_plan`, `grant`, `payer_change`, `suspended`, `closed`, `already_member` or `limit_reached` (the message says what to do); or the `Idempotency-Key` used with another body or still running. |
| 422 | `cap_cents` not whole cents from 0 to 100000000, or an unknown key. |
| 429 | The organization's rate limit. |

## Example request

```bash
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 '{ }'
```

## Example response (200)

```json
{
  "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
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/platform/put-organizations-id-shared-plan-workspaces-workspace-id
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json
