Confirm a plan quote

Confirm a plan quote

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

POST /organizations/{id}/workspaces/{workspace_id}/plan-quotes/{quote_id}/confirm
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 '{ }'
Response · 200
{
  "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"
}

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.

Parameters4 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
quote_idrequiredstring · pathThe plan quote's id (`pq_…`).
Idempotency-Keyrequiredstring · headerAny 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 body1 field
FieldTypeDescription
confirm_tokenrequiredstringThe quote's `confirm_token` (`pqct_…`) from its create response. Single use.
Response · 200 fields19 fields
FieldTypeDescription
objectrequiredenumplan_quote—
idrequiredstring`pq_…`
workspace_idrequiredstring`ws_…`
external_idrequiredstringThe workspace's `external_id` when quoted.
statusrequiredenumopen | confirmed | expired`open` until confirmed or 10 minutes pass; `confirmed` once a confirm used it.
kindrequiredenumupgrade | downgrade | lateral | start | cancel | noop`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).
currentrequiredOrganizationPlanStop—
targetrequiredOrganizationPlanStop—
due_now_centsrequiredintegerCharged 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_centsrequiredintegerUnused allowance carried into the new period (an upgrade only).
effectiverequiredenumnow | period_end—
effective_atrequiredstringWhen 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_atrequiredstring—
created_atrequiredstring—
confirmed_atrequiredstring—
hosted_invoice_urlrequiredstringAfter 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_organizationrequiredbooleanA 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_changerequiredobjectA 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_tokenstringOn create only: the single-use token the confirm takes (`pqct_…`). Stored hashed; never shown again.
200400401402403404409422429500

Search docs and guides

Search the docs and product guides.