---
title: "Soft-delete a listing"
method: DELETE
path: "/api/items/{id}"
tags: ["Listings"]
---

# Soft-delete a listing

`DELETE /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`)

Soft delete. The listing is hidden from the sale page, the dashboard, and every status-filtered read, but the document and its photos survive for 7 days and can be recovered with POST /api/items/{id}/restore. A purge job hard-deletes the document and its Storage blobs once the window closes, after which restore returns 410. Repeating the delete is a no-op success, not a 404.

## Response `200`

Deleted, or already deleted.

- object
  - `success` boolean
  - `data` object
    - `item_id` string
    - `deleted` boolean: Always true on a 200.
    - `already_deleted` boolean: Present and true only when the item was ALREADY a tombstone, so this call changed nothing. Absent on the call that performed the delete. Treat it as success either way, but do not report a fresh deletion to the user when it is set, and do not use it to infer that the restore window just started: the 7-day clock runs from the ORIGINAL delete, which may be nearly expired.

## Other responses

- `400`: The item has an active reservation. A buyer is holding it, so deleting would strand them. `error` is "This item has an active reservation. Deactivate the item first to cancel reservations, then delete it." Set the item's status to `inactive` via PUT (which cancels the reservation and notifies the buyer), then delete.
- `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.
- `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)