---
title: "Confirm a plan quote"
description: "Apply a plan quote, once: the body is its confirm_token, and Idempotency-Key is required (a retry with it answers what the first call did and never applies twice). `POST /api/v1/organizations/{id}/workspaces/{workspace_id}/plan-quotes/{quote_id}/confirm`"
url: https://www.unitpost.com/docs/platform/post-organizations-id-workspaces-workspace-id-plan-quotes-quote-id-confirm
section: "Platform API reference"
updated: 2026-11-17
---
# Confirm a plan quote

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

Apply a plan quote, once: the body is its `confirm_token`, and `Idempotency-Key` is required (a retry with it answers what the first call did and never applies twice). The change takes effect as the quote said, the same as a plan change in the dashboard. Everything the quote assumed is checked again: today's API rules, who pays, and that the workspace's plan didn't change since (`quote_stale`). A card that refuses the charge is `402 payment_failed`: nothing changed and the quote stays open until it expires. That is for an upgrade (a lateral move charges nothing now, only Stripe's proration on the next invoice): a `start` from free behaves as a paid create does, so a card that is declined or asks for authentication still answers `200` `confirmed`, with `hosted_invoice_url`; the plan starts when that invoice is paid, and unpaid it lapses after about 23 hours (nothing charged) and the workspace stays on Free. While a change is still being written back (or a first invoice waits), a new quote or confirm for the workspace is `409 conflict` with `details[0].code: "plan_change_in_progress"`. A quote with `moves_to_organization` first moves the free workspace onto the organization's billing (one of its card's workspace slots; at the limit it is `409` and nothing is charged) and, if it has no SMS purchases cap, gives it the Owner's default, as a paid create does. Every refusal frees the `Idempotency-Key`. The workspace's activity log names the organization key, and the organization's Owners and Billing members get an email about the change. 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_…`). |
| `quote_id` | path | string | yes | The plan quote's id (`pq_…`). |
| `Idempotency-Key` | header | string | yes | 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 |
| --- | --- | --- | --- |
| `confirm_token` | string | yes | The quote's `confirm_token` (`pqct_…`) from its create response. Single use. |

## Response fields (200)

| 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 |
| --- | --- |
| 200 | The confirmed quote. |
| 400 | No `Idempotency-Key` (`idempotency_key_required`), or an invalid one. |
| 401 | Missing or invalid organization key (a workspace key is refused). |
| 402 | `payment_failed` (an upgrade; a `start` answers 200 with `hosted_invoice_url` instead): the organization's card refused the charge. Nothing changed; the quote can be confirmed again once the card is fixed, until it expires. |
| 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`, as on the quote. |
| 404 | Not this key's organization, not one of its workspaces, or no such quote for that workspace. |
| 409 | `quote_expired` (quotes last 10 minutes), `quote_already_used`, `quote_stale` (the workspace's plan changed, or another plan change was confirmed after this quote was made: ask for a new one), `conflict` (as on the quote, or the card processor refused the change as sent: nothing was charged, the quote is open again until it expires, and the plan is unchanged; if a scheduled downgrade had to be cancelled for it and couldn't be put back, the message says so and a new quote shows `pending_change` null), or the `Idempotency-Key` used with another body or still running. |
| 422 | `validation_error` with `details[0].code: "plan_not_allowed"`: the Owner's API rules changed since the quote and no longer allow it. Otherwise `validation_error`: not this quote's confirm token, or an invalid body. |
| 429 | The organization's rate limit. |
| 500 | `internal_error` with `details[0].code: "plan_change_outcome_unknown"`: the change failed partway (a timeout or the card processor's own error) and may still be applying. The quote is spent; don't retry it. A new quote is `409` with `plan_change_in_progress` until the card processor confirms this change to us, for at most 24 hours; then a new quote shows whether it applied (its `current`, or `pending_change` for a downgrade; for a cancel, a quote for `free` answers `noop`). For a `noop` that cancels a scheduled change nothing is held: quote again, and `pending_change` is null if it applied. |

## Example request

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

## Example response (200)

```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-quote-id-confirm
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json
