---
title: "Close out a pickup: sold or no-show (step 2 of 2 for an API key)"
method: POST
path: "/api/reservations/{id}/pickup-confirm"
tags: ["Orders"]
---

# Close out a pickup: sold or no-show (step 2 of 2 for an API key)

`POST /api/reservations/{id}/pickup-confirm`

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/reservations/{id}/pickup-confirm`
- Auth: one of:
  - API key in header `X-ClearList-API-Key`
  - OAuth 2 (authorization code, authorization URL `https://clearlist.me/oauth/authorize`, token URL `https://clearlist.me/api/oauth/token`, scopes: `write`)

The seller's "did this pickup happen?" action. `sold` marks the reservation's items sold, completes it and emails the buyer. `noshow` cancels the reservation, returns the items to sale, frees any booked slot and advances the queue. Cannot be undone. An API key or OAuth token must send `confirmation_token` from POST /api/reservations/{id}/pickup-confirm/prepare, and the action is taken from that token. A partial close-out answers 500 with `retryable: true` and leaves the reservation active; re-run it with the same token. A reservation that is no longer active answers 200 with `outcome: already_processed` and changes nothing.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `action` 'sold' | 'noshow': Required for the seller's own session or email link. For an API key the action comes from confirmation_token; it may be echoed here and must then match (409 CONFIRMATION_MISMATCH otherwise).
  - `confirmation_token` string: Required for an API key or OAuth token. From the prepare step. Reusable for 10 minutes while the reservation is still active, so a partial close-out can be re-run.
  - `token` string: The token from the seller's pickup-check email. Not used by agents.

## Response `200`

Close-out applied, or `outcome: already_processed` when the reservation was no longer active.

- Error
  - `success` boolean, required
  - `error` string, required: Human-readable error message.
  - `code` string: Machine-readable error code, e.g. route_not_found, invalid_token, rate_limited.
  - `message` string: Detailed message.
  - `hint` string: Resolution guidance for agents.
  - `retryable` boolean: Present on refusals that are worth retrying unchanged. Currently only a wrong-conversation address confirmation, where the token is untouched and only the id was wrong. Absent means terminal.

## Other responses

- `400`: action missing or not sold/noshow (non-agent callers).
- `403`: Not this reservation's seller, or `code: CONFIRMATION_REQUIRED` when an API key sends no confirmation_token. A confirmation token that is expired, not valid, or prepared for a different conversation or reservation is refused with `code: CONFIRMATION_EXPIRED`, `CONFIRMATION_NOT_FOUND` or `CONFIRMATION_WRONG_TARGET` (the last one says the token is still valid for its own target). Nothing is written.
- `404`: Resource (or API route) not found. Returned as JSON, never HTML.
- `409`: `code: idempotency_conflict`: a request with this Idempotency-Key is still being processed; retry the same request with the same key after a few seconds. A 409 without that code is the operation's own refusal: this pickup was already handled from another device or by a concurrent request. Not retryable; read the reservation to see its state. Also `code: CONFIRMATION_MISMATCH` when an API key echoes an `action` that differs from the confirmed one; nothing changed.
- `422`: `code: idempotency_key_reuse`. While an earlier request with this Idempotency-Key is still running or succeeded within the last 24h, the key was sent to the same operation with a different body (compared byte for byte) or from a different kind of credential (signed-in session, API key, or OAuth token). Nothing was executed and the original record is untouched, so retrying with this key repeats the 422. Send the request with a new key.
- `500`: Unexpected error, or a partial close-out with `retryable: true`: re-run with the same confirmation token.

---

[API](https://skmtc.dev/clearlist/apis/clearlist-api.md) · [All operations](https://skmtc.dev/clearlist/apis/clearlist-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clearlist/apis/clearlist-api/revisions/b1c1c4221cb8?raw)