---
title: "Update a listing"
method: PUT
path: "/api/items/{id}"
tags: ["Listings"]
---

# Update a listing

`PUT /api/items/{id}`

## Request

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

Update any field on an item (price, title, description, status, etc.). This route does NOT accept an Idempotency-Key (check the parameters of an operation before sending one — this spec declares the header only on the six routes that honour it). Retry safety comes from the conflict check instead: on a timeout, re-read the item with GET and re-apply the change, and treat the "changed while you were editing" 409 below as your signal that a concurrent write landed first.

## Request body

- object

## Response `200`

Updated. The body carries the full updated item document.

- object

## Other responses

- `400`: Invalid or missing parameters.
- `401`: Missing or invalid API key.
- `403`: Either the credential does not own this item (the item exists and belongs to another seller; never retry, no key rotation or backoff changes the answer), or `code: ADDRESS_IN_PUBLIC_LISTING` when an API key or OAuth token writes the seller's stored street address into public listing text (title, description, transport_notes, condition, category, or specifications). Nothing is saved. Remove the address; to give it to a buyer, use the address share flow. A signed-in seller's own session is not checked.
- `404`: Resource (or API route) not found. Returned as JSON, never HTML.
- `409`: Three distinct conflicts share this status; read `error` to tell them apart. 1. **The item is deleted.** `error` is "This item is deleted. Restore it first: POST /api/items/{id}/restore". An edit cannot resurrect a tombstone, because that would skip the active-item capacity re-check that POST /api/items/{id}/restore runs in a transaction. Call restore, then retry the edit. 2. **The item changed while you were editing it.** `error` is "This item changed while you were editing it. Reload and try again." Your write was rejected rather than applied on top of someone else's. Re-read the item with GET and re-apply your change to the fresh document. 3. **The seller account backing the item is missing or incomplete.** `error` is "Cannot update: this seller account is missing or incomplete." An account-level inconsistency, not an edit conflict — retrying cannot fix it; surface it to the seller. None is retryable as-is: the same request repeated returns the same 409.
- `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)