- Orders
- Cancel Orders
Orders
Cancel Orders
Submit asynchronous order cancellation requests
curl --request POST \
--url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/order_cancel_requests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"customer_identifier": "<string>",
"reason": "<string>",
"notes": "<string>",
"requested_by": "<string>",
"priority": 123
}'Cancel orders asynchronously by submitting cancellation requests. The system processes cancellations in the background and provides status updates through polling or webhooks.
Important: Use this dedicated endpoint for cancellations. Do NOT use the /order_update_requests endpoint to cancel orders - that endpoint is exclusively for editing orders.
Request Body
The request body accepts an array of cancellation request objects:
Required Fields
Your unique order identifier for the order to cancel.
Cancellation reason. Common values:
customer_request- Customer initiated cancellationinventory_unavailable- Out of stockpayment_failed- Payment processing issueduplicate_order- Accidental duplicatefraud_suspected- Security concernother- Other reason (provide details in notes)
Additional context or details about the cancellation.
Email or identifier of the person requesting cancellation.
Cancellation priority (1-999). Higher values processed first.
curl -X POST "https://app.masonhub.co/{account}/api/v1/order_cancel_requests" \
-H "Authorization: Bearer your_jwt_token" \
-H "Content-Type: application/json" \
-d '[
{
"customer_identifier": "129374",
"reason": "customer_request",
"notes": "Customer changed their mind before shipment",
"requested_by": "customer.service@example.com"
}
]'
{
"records_submitted": 1,
"records_processed": 1,
"records_failed": 0,
"records_succeeded": 1,
"results": [
{
"system_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"customer_identifier": "129374",
"status": "pending",
"submitted_at": "2024-01-17T10:30:00Z"
}
]
}
Cancellation Process Flow
Submit Request
Send cancellation request to this endpoint with order identifier and reason
Receive Confirmation
API returns immediately with a system_id for tracking the request
Asynchronous Processing
MasonHub processes the cancellation in the background:
- Verifies order exists and can be canceled
- Stops fulfillment processes if in progress
- Releases allocated inventory
- Updates order status
Monitor Status
Check cancellation status via polling or webhook callbacks
Final Resolution
Receive final status: success, failed, or partial
Monitoring Cancellation Status
Track your cancellation request status using these methods:
Polling
Webhooks (Recommended)
Query the Get Order Cancels endpoint:
GET /order_cancel_requests?id=7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d
Poll every 30-60 seconds until status changes from pending to final state.
Cancellation Eligibility
Orders can be canceled based on their current status:
Cancellation Reasons
Standard cancellation reasons and their typical use cases:
customer_request
Customer initiated the cancellation through your platform
inventory_unavailable
Stock depleted or inventory discrepancy discovered
payment_failed
Payment authorization failed or was declined
duplicate_order
Accidental duplicate order submission
fraud_suspected
Security concerns or suspicious activity detected
address_undeliverable
Shipping address invalid or unserviceable
product_discontinued
Product no longer available for sale
other
Other reason - provide details in notes field
Handling Partial Cancellations
When only part of an order can be canceled:
{
"cancel_request_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"customer_identifier": "129374",
"status": "partial",
"details": {
"requested_items": 5,
"canceled_items": 3,
"shipped_items": 2,
"reason": "2 items already shipped in shipment SHIP-001"
}
}
Partial cancellations occur when some items have already been shipped. You’ll need to handle returns for shipped items separately.
Fees and Charges
Cancellation fees may apply depending on fulfillment stage:
- No fee: Orders canceled before picking starts
- Picking fee: Orders canceled after picking begins
- Full charge: Orders canceled after packing complete
Contact your MasonHub representative for your specific fee structure.
Best Practices
Cancel Quickly
Submit cancellations immediately to maximize success probability
Provide Context
Include detailed notes to help warehouse staff and for audit trails
Use Webhooks
Configure callbacks for real-time updates instead of polling
Handle Failures
Implement retry logic for failed cancellations with corrected data
Error Handling
Common error scenarios and recommended actions:
| Error Code | Scenario | Recommended Action |
|---|---|---|
| ORDER_NOT_FOUND | Order doesn’t exist | Verify customer_identifier |
| CANCELLATION_NOT_ALLOWED | Order already shipped | Initiate return process |
| DUPLICATE_REQUEST | Cancellation already submitted | Check existing request status |
| INVALID_REASON | Unknown reason code | Use valid reason from list |
Store the returned system_id for each cancellation request. You’ll need it to track the cancellation status and handle any follow-up actions.
Related Endpoints
- Get Order Cancels - Check cancellation request status
- Create Returns - For orders already shipped
- Order Cancel Resolutions - Webhook configuration
Sources
curl -X POST "https://app.masonhub.co/{account}/api/v1/order_cancel_requests" \
-H "Authorization: Bearer your_jwt_token" \
-H "Content-Type: application/json" \
-d '[
{
"customer_identifier": "129374",
"reason": "customer_request",
"notes": "Customer changed their mind before shipment",
"requested_by": "customer.service@example.com"
}
]'
curl --request POST \
--url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/order_cancel_requests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"customer_identifier": "<string>",
"reason": "<string>",
"notes": "<string>",
"requested_by": "<string>",
"priority": 123
}'{
"records_submitted": 1,
"records_processed": 1,
"records_failed": 0,
"records_succeeded": 1,
"results": [
{
"system_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"customer_identifier": "129374",
"status": "pending",
"submitted_at": "2024-01-17T10:30:00Z"
}
]
}