Orders

Reply to a buyer

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.

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)

Headers

Idempotency-Keystring

Unique client-generated key (1-255 chars from A-Za-z0-9_-:.; a UUID works well), scoped to the seller and the operation. The first successful (2xx) response is stored for 24h; retrying the identical request with the same key replays it instead of re-executing, so network-failure retries never create duplicates. A duplicate that arrives while the first is still running gets 409 idempotency_conflict. The same key with a different body (byte for byte) or a different kind of credential gets 422 idempotency_key_reuse and leaves the original record in place: send a new key. An error the operation itself returns is never stored and releases the key.

Request body

contentstring

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_tokenstring

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

Message sent.

object required

Changes

No recorded changes to this operation across all 1 revision of this API.