---
title: "Remove a workspace from the shared plan"
description: "Take a workspace off the shared plan. `DELETE /api/v1/organizations/{id}/shared-plan/workspaces/{workspace_id}`"
url: https://www.unitpost.com/docs/platform/delete-organizations-id-shared-plan-workspaces-workspace-id
section: "Platform API reference"
updated: 2026-11-17
---
# Remove a workspace from the shared plan

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

Take a workspace off the shared plan. Its usage this period stays counted on the plan. It drops to Free if its Owner's one free workspace is unused, else it needs a plan before it sends again (`drops_to`: `free` or `needs_plan`); it stays on the organization's billing, so a plan bought for it is billed to the organization. A workspace not on the shared plan answers `left: false` and nothing changes. `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`. |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | enum | yes | One of: `shared_plan_removal`. |
| `workspace_id` | string | yes | `ws_…` |
| `external_id` | string | yes | — |
| `left` | boolean | yes | False when it wasn't on the shared plan: nothing changed. |
| `drops_to` | enum \| null | yes | `free`: it is on Free (its Owner's one free workspace). `needs_plan`: it sends again once a plan is bought for it. Null when `left` is false. |

## Responses

| Status | Description |
| --- | --- |
| 200 | What the workspace dropped to. |
| 400 | An invalid `Idempotency-Key`. |
| 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, or not one of its workspaces. |
| 409 | The `Idempotency-Key` used with another request, or still running. |
| 429 | The organization's rate limit. |

## Example request

```bash
curl -X DELETE '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'
```

## Example response (200)

```json
{
  "object": "shared_plan_removal",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "left": false,
  "drops_to": "free"
}
```

## Links

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