Cancellation

A store cancels an order in two situations: the customer cancels the order, or the store accepted a shipping order it cannot ship.

In both situations, send order.cancelled only while no part of the order has shipped, by the selling shop or by the shipping shop. One event cancels the whole order. Single lines cannot be cancelled. Once a line has shipped it is a return, not a cancellation. A line has shipped once SKUU has sent tracking for it.

1. The online store sends `order.cancelled`

The online store. The customer cancels, or the store cannot ship an order it accepted. The store's platform marks the order cancelled.
The store's platform. Sends one order.cancelled with the store's order id, the time of cancellation and a reason where there is one.
SKUU. Finds the order and asks the shipping shop to stop it, then closes the order lines and frees the reserved stock.
SKUU. Answers 200, including for a cancellation it has already handled. An unknown order gets 404. If a shipping shop could not be stopped in time, 503: send the same event again.

Example: the order.cancelled event

{
  "spec_version": "1",
  "event": "order.cancelled",
  "event_id": "evt_cancel_01JABC",
  "occurred_at": "2026-09-01T10:40:00Z",
  "data": {
    "order_id": "ORD-10045",
    "cancelled_at": "2026-09-01T10:39:30Z",
    "reason": "customer changed mind"
  }
}

All fields in `data`

Field in `data`	Required	What it means
`order_id`	Required	The store's order id. As the selling shop: the id sent in `order.created`. As the shipping shop: the id returned from `POST /orders`.
`cancelled_at`	Required	When the store's platform cancelled the order.
`reason`	Optional	Shown to SKUU customer service.

If a line already shipped, SKUU answers 409 {"detail":"order_already_shipped"}. Do not resend. The customer keeps the parcel and returns it; see Returns.

2. SKUU calls `POST /cancel`

As the shipping shop the store hosts this endpoint so SKUU can stop a shipping order it created in that platform. Hosting it is optional. Shops that do not host it are called by SKUU customer service instead, who cancels the order with them by hand.

Example: the cancel request and its answer

POST {your_api_root}/cancel

{
  "external_ref": "skuu-cancel-01JABC",
  "order_id": "5001"
}

{
  "external_ref": "skuu-cancel-01JABC",
  "order_id": "5001",
  "status": "cancelled"
}

All fields in the request

Field in the request	Always present	What it means
`external_ref`	Yes	SKUU's reference for this cancellation and the idempotency key.
`order_id`	Yes	The shipping order id returned from `POST /orders`.

Check the shipment state and stop dispatch in one operation. If nothing shipped, cancel the order and release its stock reservation once. Answer 200 only when the order can no longer ship; an incomplete stop needs a 5xx, never a success. Do not refund or notify the consumer: the selling shop owns that relationship.

Answer with both references unchanged and status: "cancelled". Extra fields are ignored. The same reference on the same order returns the same answer, including for an order already cancelled. The same reference on another order is 409 idempotency_conflict. A shipped line is 409 order_already_shipped and changes nothing. An unknown order is 404 unknown_order. SKUU retries network failures, 429 and 5xx three times with the identical signed body.

The next page is Returns. The exact contract is on Send an event and Cancel a shipping order.

1. The online store sends order.cancelled

2. SKUU calls POST /cancel

1. The online store sends `order.cancelled`

2. SKUU calls `POST /cancel`