---
title: "Cancel one order"
method: POST
path: "/orders/{id}/cancel"
tags: ["orders"]
---

# Cancel one order

`POST /orders/{id}/cancel`

## Request

- Base URL: `https://0.0.0.0:3000/api/v1`
- URL: `https://0.0.0.0:3000/api/v1/orders/{id}/cancel`
- Auth: API key in header `x-api-key`

Cancels the order and records who did it and why. It stays readable as `CANCELLED`; nothing is deleted.

A seller key cancels its OWN order while it is `PENDING` or `ON_HOLD` and has not reached a warehouse. After that the work has started — ask support. A warehouse or admin key cancels any order that is not finished.

No key cancels an order that has been charged: that answers 409 with `reason: "paid"`. Request a refund instead — the refund pays the seller back and cancels the order in the same step. An order the warehouse already has answers 409 with `reason: "with-warehouse"`; one already finished, 409 with `reason: "invalid-transition"`.

The body is optional. Send an `Idempotency-Key` when you may retry: a replay returns the first answer.

## Path parameters

- `id` integer, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `reason` string: Optional. Why — recorded on the order's history. 500 characters at most.

## Response `200`

The order in full, now `CANCELLED`.

## Other responses

- `401`: No key, or a key that is unknown, revoked or expired. One message for all four — telling you which would confirm to a guesser that a key exists.
- `403`: The key is valid but its owner may not do this.
- `404`: No such record — including records that exist but belong to someone else. The API never confirms another seller's ids.
- `409`: The request contradicts the current state of the record.
- `422`: The body or query is malformed. Field-level detail arrives in `error.fields`.
- `429`: Over the per-key limit. `Retry-After` says how many seconds to wait.
- `500`: Our fault. `error.request_id` matches the X-Request-Id header — quote it to support.

---

[API](https://skmtc.dev/opcreative/apis/opcreative-api.md) · [All operations](https://skmtc.dev/opcreative/apis/opcreative-api/llms.txt) · [OpenAPI document](https://skmtc.dev/opcreative/apis/opcreative-api/revisions/105bb30aa87e?raw)