Cancel an order
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Path Parameters
Body
TAKES NO PARAMETERS, and an empty body is the ordinary call. The empty key set is ENFORCED rather than ignored: reason, refund, restock and notify_customer are each refused BY NAME, so a client that assumes this route works like another platform's cancel is told the field does nothing instead of reading the 200 as agreement to it. There is no reason column on an order, money is the payment module's, the inventory release is unconditional so there is nothing to opt into, and the shopper email has no suppression path. The provenance and snapshot keys (id, display_id, created_at, updated_at, currency_code and every _minor total) are refused the same way, because the server owns them and an order's money is snapshotted at placement; status is refused because cancelling IS the one transition this api can verify, and metadata belongs to PUT /api/v1/orders/{orderId}/metadata. IT IS NOT REVERSIBLE. cancelled is terminal in the order state machine, so no route moves the order back and the record stands cancelled for good. It is a POST rather than a DELETE because the order row survives: nothing is removed. WHAT IT DOES TO MONEY: in the same transaction it returns the promotion campaign budget the order's discount drew and credits the gift card, store credit and loyalty tenders back to the shopper, every figure in integer minor units. IT DOES NOT REFUND A CARD CHARGE and calls nothing in the payment module, which is why an order that is already PAID is refused with 409 cancel_requires_refund instead of being cancelled with the charge still captured. Refund it from the dashboard first. WHAT IT DOES TO STOCK: it releases the order's inventory reservations back to available in that same transaction. The release is mandatory here rather than best effort, so a deployment that has not wired it is refused with 503 cancel_unavailable BEFORE the transaction opens. Nothing half-happens, and the order is never left cancelled with its stock stranded as reserved. It also emails the shopper a cancellation and enqueues the orders/cancelled webhook to the store's endpoints. A RETRY IS SAFE PAST THE IDEMPOTENCY WINDOW. Replaying the Idempotency-Key returns the recorded response, and a retry arriving after the lease has expired re-executes, finds the order already cancelled and answers 200 as a no-op: no second status write, no second webhook and no second shopper email. An order in a status that cannot reach cancelled (fulfilled, completed, refunded) is 409 invalid_transition. The response is the whole order in the read's shape, byte-identical to GET /api/v1/orders/{orderId}, never a 204.
Response
Success