Skip to main content
POST
{orders_api_base_url}
/
orders
/
cancel
Cancel Order
curl --request POST \
  --url 'https://api.example.com/{{orders_api_base_url}}/orders/cancel/' \
  --header 'Content-Type: application/json' \
  --data '
{
  "store_id": "<string>",
  "order_id": "<string>",
  "reason": "<string>",
  "description": "<string>",
  "initiated_by": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "order_id": "<string>",
  "cancellation_id": "<string>",
  "refund_amount": "<string>",
  "refund_status": "<string>",
  "platform_notified": true,
  "customer_notified": true
}
This endpoint cancels an order regardless of its current status and handles all necessary cleanup including customer notifications, refunds, inventory adjustments, and delivery platform communications.
Canceling orders frequently can negatively impact your store’s rating on delivery platforms. Use this endpoint judiciously and consider alternative solutions when possible.

​
Request Body

​
store_id
string
required
The unique identifier of the store canceling the order
​
order_id
string
required
The unique identifier of the order to cancel
​
reason
string
required
Reason for cancellation. Must be one of the predefined reason codes.
​
description
string
Additional details about the cancellation reason
​
initiated_by
string
required
Employee ID who initiated the cancellation

​
Cancellation Reason Codes

Store-Related Reasons:
  • OUT_OF_STOCK - Required items are not available
  • KITCHEN_CLOSED - Kitchen is closed or unable to prepare
  • EQUIPMENT_FAILURE - Equipment malfunction preventing preparation
  • STAFF_SHORTAGE - Insufficient staff to fulfill order
  • STORE_EMERGENCY - Emergency situation at store
Customer-Related Reasons:
  • CUSTOMER_REQUEST - Customer requested cancellation
  • PAYMENT_ISSUE - Payment could not be processed
  • DELIVERY_ADDRESS_ISSUE - Delivery address problems
Platform-Related Reasons:
  • PLATFORM_ERROR - Technical issue with delivery platform
  • DUPLICATE_ORDER - Order was duplicated in system
  • FRAUD_SUSPECTED - Suspected fraudulent order
Other Reasons:
  • WEATHER_RELATED - Severe weather preventing fulfillment
  • OTHER - Other reason (requires description)

​
Response

​
success
boolean
Indicates whether the order was successfully canceled
​
message
string
Confirmation message or error details
​
order_id
string
The canceled order’s unique identifier
​
cancellation_id
string
Unique identifier for the cancellation record
​
refund_amount
string
Amount that will be refunded to customer
​
refund_status
string
Status of the refund process
​
platform_notified
boolean
Whether the delivery platform was successfully notified
​
customer_notified
boolean
Whether the customer was successfully notified

​
Request Example

{
  "store_id": "449235c1-3d04-4519-998b-40d2a621e5e0",
  "order_id": "35d18f08-6d54-421d-9476-8cef629111bc",
  "reason": "OUT_OF_STOCK",
  "description": "Main ingredient not available due to supply chain issue",
  "initiated_by": "870a05c1-bbbf-48ab-a757-e28ae0a2b2a8"
}

​
Response Example

{
  "success": true,
  "message": "Order successfully canceled and all parties notified",
  "order_id": "35d18f08-6d54-421d-9476-8cef629111bc",
  "cancellation_id": "c4f2d9e8-1a3b-4c5d-8e9f-2a3b4c5d6e7f",
  "refund_amount": "41.02",
  "refund_status": "processing",
  "platform_notified": true,
  "customer_notified": true
}
When an order is canceled, the following automated processes occur:
  1. Order Status Update: Status changed to “canceled”
  2. Inventory Release: Any reserved inventory is released back to available stock
  3. Refund Initiation: Automatic refund processing begins
  4. Platform Notification: Delivery platform is notified with reason
  5. Customer Notification: Customer receives cancellation notification
  6. Analytics Update: Cancellation metrics are updated for reporting
  7. Audit Trail: Complete cancellation record is created for compliance
Refund Timing: Refunds typically process within 3-5 business days, but the exact timing depends on the customer’s payment method and the delivery platform’s policies.
Best Practice: When possible, contact the customer directly before canceling to explore alternatives or explain the situation. This can help maintain customer satisfaction even in difficult situations.

​
Error Responses

Order Cannot Be Canceled
{
  "success": false,
  "message": "Order is already completed and cannot be canceled",
  "error_code": "ORDER_NOT_CANCELABLE"
}
Invalid Reason Code
{
  "success": false,
  "message": "Invalid cancellation reason provided",
  "error_code": "INVALID_REASON"
}
Platform Communication Failed
{
  "success": true,
  "message": "Order canceled but platform notification failed",
  "order_id": "35d18f08-6d54-421d-9476-8cef629111bc",
  "platform_notified": false,
  "warning": "Manual platform notification may be required"
}
Manual Follow-up: If platform_notified is false, you may need to manually notify the delivery platform to avoid fulfillment conflicts.