---
title: "Restore a soft-deleted listing"
method: POST
path: "/api/items/{id}/restore"
tags: ["Listings"]
---

# Restore a soft-deleted listing

`POST /api/items/{id}/restore`

## Request

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

Undoes DELETE /api/items/{id} inside the 7-day window. The item returns to the status it held before the delete, except that a previously `reserved` item comes back `available` (the reservation that justified it is long gone) and an item that no longer fits the seller's active-item limit comes back `inactive` rather than being refused. Pass an Idempotency-Key: this operation is NOT self-idempotent, and a retry without one reports 409 "This item is not deleted" for a restore that in fact succeeded.

## Headers

- `Idempotency-Key` string

## Response `200`

Restored.

- object
  - `success` boolean
  - `data` object
    - `item_id` string
    - `status` 'available' | 'taken' | 'inactive': The status the item was restored TO. Not necessarily the status it had before the delete.
    - `downgraded_to_inactive` boolean: True when the seller was at their active-item limit, so the item was restored as `inactive` instead of the status it had before the delete. The restore succeeded and the seller's work is back, but the listing is NOT visible on the sale page. Surface this: reporting a plain success here leaves the seller believing a hidden item is live. `message` carries seller-facing wording naming the limit.
    - `message` string: Present only when downgraded_to_inactive is true.

## Other responses

- `400`: Invalid or missing parameters.
- `401`: Missing or invalid API key.
- `403`: Authenticated, but the credential does not own this resource. Distinct from 404: the resource exists and belongs to another seller. Never retry: no key rotation or backoff changes the answer.
- `404`: Resource (or API route) not found. Returned as JSON, never HTML.
- `409`: Nothing to restore. Either the item is not deleted (`error` is "This item is not deleted") or the seller account that owns it is missing or incomplete. Not retryable: repeating the call returns the same 409. If you sent an Idempotency-Key on the original attempt, retry with that same key instead. A 409 here after a request that timed out usually means the first attempt committed and you are seeing the follow-up call, not a failure. Also returned with `code: idempotency_conflict` while a request with the same Idempotency-Key is still being processed; that one is worth retrying with the same key after a few seconds. A 409 without that code is the operation's own refusal: read `error`.
- `410`: The 7-day restore window has passed. `error` is "The restore window for this item has passed." The listing and its photos are unrecoverable; there is no appeal path and no retry. Refused on the window rather than on the document still existing, so the answer does not depend on when the purge job last ran.
- `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.
- `429`: Too many requests.
- `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)