Cancel Order
POST/api/pinnacle/instances/:instance/orders/:order/cancel
Recalls an order at Pinnacle (CancelOrder). On success the order is marked cancelled and, if it has not shipped, its fulfillment order is voided. Pinnacle may refuse (for example when delivery is already scheduled); the response is then 422 with code cancel_refused, the refusal code and label, and the current order (the refusal code is also stored on the order). Cancelling an already cancelled or closed order returns it unchanged.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Body fields:
- reason (string, required, 3–250 characters): sent to Pinnacle with the cancellation.
Orders without a tracking number whose registration attempt never received a result from Pinnacle are checked with Pinnacle first. If Pinnacle created the delivery, it is cancelled as above. If Pinnacle confirms no delivery was created, the response is 200 with code not_created and the unchanged order; nothing is cancelled and the fulfillment order stays open. If Pinnacle cannot be queried to verify the attempt, the response is 422 with code unverified; retry the request later. If Pinnacle answered an earlier registration with "already in queue" (it holds the request but has not registered it yet), the response is 422 with code queued: SKU.io cannot cancel a queued request (cancelling needs a tracking number), so cancel it with MWD directly, or retry once Pinnacle has registered it. An empty lookup never releases a queued request; only its registration (adopted automatically) or Pinnacle reporting it cancelled does.
Other 422 codes: not_registered (the order was never registered with Pinnacle and has no registration attempt to verify) and api_error (Pinnacle could not be reached or returned an error).
Authentication: requires a Bearer token (Personal Access Token).
Requires the fulfillment_orders.cancel permission; without it the request is refused with 403.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.