Skip to main content

Cancel an order with optional refund amount

PUT 
/api/v1/orders/:orderId/cancel

This endpoint cancels an order and optionally initiates a refund. Inventory is restored for cancelled items.

Authentication: Requires Private API Key (sk_*)

Cancellation Behavior:

  • Order status changes to "cancelled"
    • Inventory quantities are restored for all order items
    • Refund is initiated if refundAmount provided (asynchronous process)
    • Customer receives cancellation notification
    • order.cancelled webhook is triggered
    • If refund initiated, order.refunded webhook triggered when complete

Use Cases:

  • Customer-requested cancellations
    • Fraud prevention and order holds
    • Out-of-stock order cancellations
    • Order management and cleanup

Important Notes:

  • Refunds may take several days to process depending on payment method
    • Partial refunds are supported by specifying refundAmount
    • Cannot cancel orders that are already delivered
    • Cancellation is logged in order history

Error Scenarios:

  • 404 NOT FOUND - Order not found (Error code: ORDER_NOT_FOUND)
    • 400 BAD REQUEST - Invalid cancellation (already cancelled/delivered, invalid refund amount) (Error code: INVALID_CANCELLATION or INVALID_REFUND_AMOUNT)
    • 401 UNAUTHORIZED - Invalid or missing API key (Error code: INVALID_API_KEY)
    • 403 FORBIDDEN - API key doesn't have access to this store (Error code: NO_STORE_ACCESS)

Request​

Responses​

Order cancelled successfully - refund processing if requested