Cancel an order and refund its payments
POST/orders/:orderId/cancellations
Cancels the given quantities of one or more order items, or the whole order with cancelWholeOrder: true, and with refundPayments: true refunds the payments of what you cancel. A payment is refunded in full: a captured payment is refunded for what is left of it, and one not captured yet is voided. So a payment is refunded only when nothing it paid for is left to ship and none of it has shipped; a request that would leave part of a payment is refused. Refunds are made with your own permissions, so your role must be allowed to refund payments. If your fulfillment provider already has the order (externalOrderId is set), only the whole order can be cancelled: the provider is asked to cancel it first, and the order is cancelled and refunded only if the provider confirms. If it cannot cancel it, for example because it has shipped, nothing changes and the response says why. If a refund fails before anything is cancelled, nothing is cancelled. With refundPayments: false the order is cancelled as by POST /orders/{orderId}/cancel, and nobody is refunded.
Request
Responses
- 200
- 202
- 400
- 401
- 403
- 404
- 413
- 429
- 500
- 503
- 504
The merchant is entitled but its OMS environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to an active-entitled merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.
The request was rejected. type is invalid_request_error; when the failure is a validation failure code is validation_failed and errors lists every problem found, with field-attributable entries prefixed by the field’s path.
No credentials were supplied, or the identity token / secret key is not valid for the target merchant. type is authentication_error.
The credentials are valid but lack the permission this operation requires. type is permission_error.
No resource exists with the requested identifier. type is not_found_error.
The request exceeded a limit on what this API accepts and was refused before the operation ran, so nothing was created or changed. The body must be under 4 MB. type is invalid_request_error, and message names the limit that was met. Reduce the request below the limit and send it again.
Too many requests. The rate limit is applied per client across all operations. type is rate_limit_error.
The request could not be completed because of an unexpected error. type is api_error.
A dependency needed to serve the request is temporarily unavailable — for every operation the auth service that verifies credentials and resolves entitlement, and on the provisioning routes also the ODUS API the OMS reconciles against. type is api_error. Unlike a plain 500 the condition is transient rather than a fault in the request, so it is worth retrying with backoff.
The request exceeded the processing time limit and was abandoned. type is api_error and code is timeout — unlike a plain 500 the request may still have taken effect.