---
title: "Quote a plan change"
description: "What moving a workspace to plan and tier_index would do; nothing is changed or charged. `POST /api/v1/organizations/{id}/workspaces/{workspace_id}/plan-quotes`"
url: https://www.unitpost.com/docs/platform/post-organizations-id-workspaces-workspace-id-plan-quotes
section: "Platform API reference"
updated: 2026-11-17
---
# Quote a plan change

`POST /api/v1/organizations/{id}/workspaces/{workspace_id}/plan-quotes`

What moving a workspace to `plan` and `tier_index` would do; nothing is changed or charged. `kind` is `upgrade` (now: the new price is charged in full, the billing period restarts, unused allowance carries over), `downgrade` (at the end of the period already paid), `lateral` (now), `start` (from free: now, on the organization's card), `cancel` (to free: the plan ends at the period end) or `noop`. The answer has the prices before and after, `due_now_cents`, `effective_at` and a single-use `confirm_token`, returned only here. A quote lasts 10 minutes. `pending_change` shows a downgrade already scheduled for the period end; with one, a quote for the current plan and tier is a `noop` whose confirm cancels it, so the workspace keeps its plan. On a workspace the organization pays for; or on a free workspace that pays for itself, a paid plan is a `start` billed to the organization (`moves_to_organization: true`), only while organization billing is on. Within the Owner's API rules: an allowed plan at a price no higher than their largest plan price (with none set, the lowest price of each allowed plan). 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 |
| --- | --- | --- | --- |
| `plan` | string | yes | `free`, or a paid plan the Owner's API rules allow. |
| `tier_index` | integer | no | The stop on the paid plan's price ladder (default 0, its lowest price). Ignored for `free`. |

## Response fields (201)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | enum | yes | One of: `plan_quote`. |
| `id` | string | yes | `pq_…` |
| `workspace_id` | string | yes | `ws_…` |
| `external_id` | string | yes | The workspace's `external_id` when quoted. |
| `status` | enum | yes | `open` until confirmed or 10 minutes pass; `confirmed` once a confirm used it. One of: `open`, `confirmed`, `expired`. |
| `kind` | enum | yes | `upgrade`: now, charged in full, the period restarts, unused allowance carries over. `downgrade`: at the period end. `lateral`: now. `start`: from free, now. `cancel`: to free, at the period end. `noop`: the plan stays as it is; with a `pending_change`, the confirm cancels it (nothing charged). One of: `upgrade`, `downgrade`, `lateral`, `start`, `cancel`, `noop`. |
| `current` | OrganizationPlanStop | yes | — |
| `target` | OrganizationPlanStop | yes | — |
| `due_now_cents` | integer | yes | Charged to the organization's card on confirm: the new monthly price on an upgrade or a start, else 0 (before any discount). An upgrade restarts the billing period, so usage beyond the old plan's allowance this period, if any, is billed on the same invoice and is not in this number. |
| `carryover_cents` | integer | yes | Unused allowance carried into the new period (an upgrade only). |
| `effective` | enum | yes | One of: `now`, `period_end`. |
| `effective_at` | string | yes | When the change takes effect (once confirmed, when it did or will). Null for a `noop`, except one on a plan already set to end, where it is when the plan ends. |
| `expires_at` | string | yes | — |
| `created_at` | string | yes | — |
| `confirmed_at` | string | yes | — |
| `hosted_invoice_url` | string | yes | After a confirm from free (`start`): the organization's card was declined or asked for authentication. The plan starts when this invoice is paid; unpaid, it lapses after about 23 hours, nothing is charged and the workspace stays on Free. Null otherwise. |
| `moves_to_organization` | boolean | yes | A free workspace that pays for itself, started on a paid plan billed to the organization: the confirm moves it onto the organization's billing first. |
| `pending_change` | object | yes | A downgrade already scheduled for the end of the period when the quote was made: the plan and stop it moves to, and when. Null when none is scheduled. With one, a quote for the current plan and tier is a `noop` whose confirm cancels it, so the workspace keeps its plan; an upgrade or a lateral move replaces it, another downgrade replaces it, and a cancel to free ends the plan instead. |
| `confirm_token` | string | no | On create only: the single-use token the confirm takes (`pqct_…`). Stored hashed; never shown again. |

## Responses

| Status | Description |
| --- | --- |
| 201 | The quote, with its confirm token. |
| 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 `workspace_suspended`, for a free workspace that pays for itself starting a paid plan: the organization has a suspended workspace, or the key's creator owns one. |
| 404 | Not this key's organization, or not one of its workspaces. |
| 409 | `conflict`: the workspace pays for itself on a paid plan (its own Owner changes it), is closed, has a change of who pays scheduled, is on a plan Unitpost's team set up, has a plan set to end (resume it first), or a paid plan needs the organization's card and there is none. For a free workspace that pays for itself, `error.details[0].code` is `organization_billing_off` (organization billing is off: an Owner or Billing member adds the organization's card on Organization → Billing) or `workspace_limit_reached` (the organization's card pays for as many workspaces as it may), or the workspace has a disputed payment (support changes who pays). Also `conflict` with `details[0].code: "plan_change_in_progress"`: an earlier change of this workspace isn't written back yet (or its first invoice waits for payment). The message names that change's quote; ask for a new quote in a minute: once it is answered, its `current` shows an upgrade, lateral move or start, its `pending_change` a downgrade, and a quote for `free` answers `noop` after a cancel. |
| 422 | `validation_error` with `details[0].code: "plan_not_allowed"`: the Owner's API rules don't allow the plan, or its price is above their largest plan price (the message names it; an Owner raises it on Organization → API). Otherwise `validation_error`: a tier the plan doesn't have, or an invalid body. |
| 429 | The organization's rate limit. |

## Example request

```bash
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123/plan-quotes' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
```

## Example response (201)

```json
{
  "object": "plan_quote",
  "id": "id_123",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "status": "open",
  "kind": "upgrade",
  "current": {
    "plan": "string",
    "tier_index": 0,
    "price_monthly_cents": 0
  },
  "target": {
    "plan": "string",
    "tier_index": 0,
    "price_monthly_cents": 0
  },
  "due_now_cents": 0,
  "carryover_cents": 0,
  "effective": "now",
  "effective_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "confirmed_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com",
  "moves_to_organization": false,
  "pending_change": {
    "plan": "string",
    "tier_index": 0,
    "effective_at": "2026-01-01T00:00:00.000Z"
  },
  "confirm_token": "string"
}
```

## Links

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