---
title: "Set a workspace's shared plan cap"
description: "Set what a workspace on the shared plan may draw from it each period, allowance and overage together, in cents (cap_cents; 0 stops it drawing at all, null removes the cap). `PATCH /api/v1/organizations/{id}/shared-plan/workspaces/{workspace_id}`"
url: https://www.unitpost.com/docs/platform/patch-organizations-id-shared-plan-workspaces-workspace-id
section: "Platform API reference"
updated: 2026-11-17
---
# Set a workspace's shared plan cap

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

Set what a workspace on the shared plan may draw from it each period, allowance and overage together, in cents (`cap_cents`; 0 stops it drawing at all, null removes the cap). At its cap only that workspace pauses (`quota_exceeded`); caps may add up to more than the plan. 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_…`). |

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cap_cents` | integer | yes | Its cap, in cents a period: 0 stops it drawing, null removes the cap. |

## 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 | 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. |
| 404 | Not this key's organization, not one of its workspaces, or (`details[0].code: "not_a_member"`) a workspace that isn't on the shared plan. |
| 422 | `cap_cents` missing, not whole cents from 0 to 100000000, or an unknown key. |
| 429 | The organization's rate limit. |

## Example request

```bash
curl -X PATCH '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/patch-organizations-id-shared-plan-workspaces-workspace-id
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json
