---
title: "Get the shared plan"
description: "The organization's shared plan: one plan whose allowance its workspaces share. `GET /api/v1/organizations/{id}/shared-plan`"
url: https://www.unitpost.com/docs/platform/get-organizations-id-shared-plan
section: "Platform API reference"
updated: 2026-11-17
---
# Get the shared plan

`GET /api/v1/organizations/{id}/shared-plan`

The organization's shared plan: one plan whose allowance its workspaces share. `approved` says whether Unitpost's team turned it on for the organization (it is never on by default: an Owner or Billing member asks on Organization → Billing, `requested_at`). `status` is `none` until a plan is bought there, then the plan's status. With a plan: its `plan`, `tier_index` and list `price_monthly_cents`, the billing period, `cancel_at` (set to end at the period end), the shared `allowance_cents`, what its workspaces drew this period (`used_cents`, `overage_cents` beyond the allowance), the overage band's size (`overage_cap_cents`, null for no band), `paused` (the allowance and band are used up: every workspace on it stops sending until the period renews), `overage_frozen` (Unitpost paused overage: sending stops at the allowance) and how many workspaces it covers (`workspace_limit`) and has (`workspaces`). Buying, upgrading and ending the plan, and raising its workspace number, are done in the dashboard. Takes an organization key (`ok_live_…`) with `organizations:read`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The organization's id (`org_…`), from `GET /whoami` or Organization → API. |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | enum | yes | One of: `shared_plan`. |
| `approved` | boolean | yes | Unitpost's team turned the shared plan on for the organization; it is never on by default. |
| `requested_at` | string | yes | When an Owner or Billing member asked for it (Organization → Billing); null if nobody has. |
| `status` | enum | yes | `none` until a plan is bought; then the plan's status. `past_due` keeps its workspaces but takes no new ones; `canceled` once it ended (its workspaces left it). One of: `none`, `active`, `trialing`, `past_due`, `paused`, `canceled`. |
| `plan` | string | yes | The plan's key (`pro` is Starter, `scale` is Growth); null with none. |
| `tier_index` | integer | yes | The stop on the plan's price ladder. |
| `price_monthly_cents` | integer | yes | The stop's list price a month, before any discount or promotion code. |
| `period_start` | string | yes | — |
| `period_end` | string | yes | — |
| `cancel_at` | string | yes | Set to end then (the period end); null while it renews. |
| `allowance_cents` | integer | yes | The allowance its workspaces share each period, in cents of sending (email, SMS, WhatsApp). |
| `used_cents` | integer | yes | What its workspaces drew this period, including workspaces that left during it. 0 with no plan. |
| `overage_cents` | integer | yes | The part of `used_cents` beyond the allowance, billed at the plan's overage rate. |
| `overage_cap_cents` | integer | yes | The overage band: how far past the allowance its workspaces may send in a period. Null: no band. |
| `paused` | boolean | yes | The allowance and the band are used up (only the allowance while `overage_frozen`): every workspace on the plan stops sending until the period renews or the plan is upgraded. |
| `overage_frozen` | boolean | yes | Unitpost's team paused overage on the plan (a disputed charge): sending stops at the allowance. |
| `workspace_limit` | integer | yes | How many workspaces the plan covers (Starter 3, Growth 10, unless Unitpost's team set another number). Before a plan is bought, the number set for the organization, or null for the plan's own. |
| `workspaces` | integer | yes | How many workspaces are on it now. |

## Responses

| Status | Description |
| --- | --- |
| 200 | The shared plan. |
| 401 | Missing or invalid organization key (a workspace key is refused). |
| 403 | API access not approved for the organization, the key lacks the capability, or no User-Agent. |
| 404 | Not this key's organization, or not one of its workspaces. |
| 429 | The organization's rate limit. |

## Example request

```bash
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/shared-plan' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
```

## Example response (200)

```json
{
  "object": "shared_plan",
  "approved": false,
  "requested_at": "2026-01-01T00:00:00.000Z",
  "status": "none",
  "plan": "string",
  "tier_index": 0,
  "price_monthly_cents": 0,
  "period_start": "2026-01-01T00:00:00.000Z",
  "period_end": "2026-01-01T00:00:00.000Z",
  "cancel_at": "2026-01-01T00:00:00.000Z",
  "allowance_cents": 0,
  "used_cents": 0,
  "overage_cents": 0,
  "overage_cap_cents": 0,
  "paused": false,
  "overage_frozen": false,
  "workspace_limit": 1,
  "workspaces": 0
}
```

## Links

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