---
title: "Reply to a buyer"
method: POST
path: "/api/conversations/{id}"
tags: ["Orders"]
---

# Reply to a buyer

`POST /api/conversations/{id}`

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/conversations/{id}`
- 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`)

Sends a message to the buyer. NOT naturally idempotent: a reply emails the buyer, so a retry after a timeout or 500 sends them a second copy of the same message. Always pass an Idempotency-Key here.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `content` string: Message body. Trimmed and truncated to 2000 characters server-side. Required for the seller's own session. For an API key the text comes from confirmation_token; `content` may be sent to echo it, and must then match the confirmed text exactly (409 CONFIRMATION_MISMATCH otherwise).
  - `type` 'text' | 'address_share' | 'pickup_confirmed': An API key may only send `text`. `address_share` is refused (403 USE_ADDRESS_FLOW): an address travels the confirmed two-step flow (share_address then confirm_address_share) or not at all. `pickup_confirmed` is refused (403 USE_CONFIRM_PICKUP): close a pickup with POST /api/reservations/{id}/pickup-confirm.
  - `confirmation_token` string: Required for an API key or OAuth token. From POST /api/conversations/{id}/reply/prepare, after the seller has seen the message and recipient. The message sent is the text frozen in the token. Single use, valid for 10 minutes.

## Response `200`

Message sent.

- object

## Other responses

- `400`: Invalid or missing parameters.
- `401`: Missing or invalid API key.
- `403`: Either the credential does not own this conversation, or `type` was `address_share` and the credential is an API key. An address cannot be sent as an ordinary message. Agents share one through the confirmed flow instead: POST /api/conversations/{id}/address/prepare names the recipient and returns a confirmation token, then POST /api/conversations/{id}/address sends it. No retry or scope change makes this route accept an address_share. Also `code: ADDRESS_USE_SHARE_FLOW` when an API key or OAuth token sends a text message containing the seller's stored street address, to any buyer, reserved or not. Nothing is written. Not retryable: share the address through the confirmed flow above, then send any other details as a separate message. Also `code: USE_CONFIRM_PICKUP` when an API key or OAuth token sends `type: pickup_confirmed`; close a pickup with POST /api/reservations/{id}/pickup-confirm instead. A signed-in seller's own session is not checked by either rule. Also `code: CONFIRMATION_REQUIRED` when an API key or OAuth token sends with no confirmation_token: prepare the message first. 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. Also `code: CONFIRMATION_ALREADY_USED`: this confirmation token already sent its message. Do not send again; read the conversation to see it. Also `code: CONFIRMATION_MISMATCH`: `content` was sent and differs from the confirmed text; nothing was sent and the token is still usable. A 409 without that code is the operation's own refusal.
- `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 server error.

---

[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)