- Orders
- Get Order Cancels
Orders
Get Order Cancels
Retrieve status and details of order cancellation requests
curl --request GET \
--url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/order_cancel_requests \
--header 'Authorization: Bearer <token>'Retrieve the status and details of previously submitted order cancellation requests. Use this endpoint to monitor the asynchronous processing of cancellations and verify successful order cancellations.
Cancellation requests are processed asynchronously. Poll this endpoint or configure webhooks to track completion status.
Query Parameters
Filter and retrieve cancellation requests with these parameters:
Filter by cancellation request system ID (UUID). Returns specific cancellation request.
Filter by customer identifier. Returns all cancellation requests for a specific order.
Filter by request status:
pending- Awaiting processingprocessing- Currently being processedsuccess- Cancellation completedfailed- Cancellation failedpartial- Some items canceled, others not
Maximum number of records to return (1-1000).
Number of records to skip for pagination.
Filter requests created after this timestamp (RFC3339 format).
Filter requests created before this timestamp (RFC3339 format).
Filter requests resolved after this timestamp (RFC3339 format).
Filter requests resolved before this timestamp (RFC3339 format).
Filter by cancellation reason (e.g., “customer_request”, “inventory_unavailable”).
# Get specific cancellation request by ID
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_cancel_requests?id=7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d" \
-H "Authorization: Bearer your_jwt_token"
# Get all cancellation requests for an order
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_cancel_requests?cid=129374" \
-H "Authorization: Bearer your_jwt_token"
# Get pending cancellation requests
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_cancel_requests?status=pending&limit=50" \
-H "Authorization: Bearer your_jwt_token"
{
"total_count": 2,
"limit": 100,
"offset": 0,
"cancel_requests": [
{
"system_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"customer_identifier": "129374",
"status": "success",
"reason": "customer_request",
"notes": "Customer changed their mind before shipment",
"requested_by": "customer.service@example.com",
"submitted_at": "2024-01-17T10:30:00Z",
"resolved_at": "2024-01-17T10:31:45Z",
"processing_time_ms": 1450,
"cancellation_details": {
"items_canceled": 2,
"inventory_released": true,
"order_status_before": "processing",
"order_status_after": "canceled",
"refund_required": true
}
},
{
"system_id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
"customer_identifier": "129375",
"status": "failed",
"reason": "customer_request",
"notes": "Attempted cancellation after shipment",
"requested_by": "support@example.com",
"submitted_at": "2024-01-17T11:00:00Z",
"resolved_at": "2024-01-17T11:00:05Z",
"processing_time_ms": 50,
"error": {
"code": "ORDER_ALREADY_SHIPPED",
"message": "Cannot cancel order that has been shipped",
"details": {
"order_status": "fulfilled",
"shipped_at": "2024-01-17T09:00:00Z",
"tracking_number": "1Z999AA10123456784"
}
}
}
]
}
Response Fields
Unique identifier for the cancellation request
Your order reference ID
Current status of the cancellation request:
pending- Queued for processingprocessing- Currently being canceledsuccess- Cancellation completedfailed- Cancellation could not be completedpartial- Some items canceled, others not
Cancellation reason code provided in request
Additional context provided with cancellation
Identifier of person/system that requested cancellation
Timestamp when cancellation was requested
Timestamp when processing completed (null if pending)
Time taken to process the cancellation in milliseconds
Detailed information about the cancellation:
items_canceled- Number of items successfully canceledinventory_released- Whether inventory was releasedorder_status_before- Order status before cancellationorder_status_after- Order status after cancellationrefund_required- Whether refund processing is needed
Error details if cancellation failed
Cancellation Request Lifecycle
Track cancellation requests through their processing stages:
pending
Request received and queued for processing
processing
System actively canceling the order:
- Stopping fulfillment processes
- Releasing inventory allocations
- Updating order status
Resolution
Final status determined:
success- Order fully canceledfailed- Cancellation not possiblepartial- Some items canceled
Polling Implementation
Efficiently monitor cancellation status with polling:
import time
import requests
def monitor_cancellation(cancel_id, headers, max_wait=300):
"""
Poll for cancellation completion with exponential backoff
"""
url = f"https://app.masonhub.co/{{account}}/api/v1/order_cancel_requests"
start_time = time.time()
poll_interval = 5 # Start with 5 seconds
while time.time() - start_time < max_wait:
response = requests.get(
url,
headers=headers,
params={"id": cancel_id}
)
data = response.json()
if data["cancel_requests"]:
request = data["cancel_requests"][0]
status = request["status"]
if status in ["success", "failed", "partial"]:
return request
print(f"Status: {status}, waiting {poll_interval}s...")
time.sleep(poll_interval)
# Exponential backoff, max 60 seconds
poll_interval = min(poll_interval * 1.5, 60)
raise TimeoutError(f"Cancellation {cancel_id} not resolved in {max_wait}s")
# Usage
result = monitor_cancellation("7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d", headers)
print(f"Cancellation {result['status']}: {result.get('cancellation_details')}")
Cancellation Scenarios
Different cancellation outcomes and their handling:
Full Cancellation
Partial Cancellation
Failed Cancellation
Entire order successfully canceled:
{
"status": "success",
"cancellation_details": {
"items_canceled": 5,
"inventory_released": true,
"order_status_after": "canceled",
"refund_required": true
}
}
Next Steps:
- Process refund if payment captured
- Send cancellation confirmation to customer
- Update internal order tracking
Common Error Codes
Bulk Cancellation Monitoring
Monitor multiple cancellation requests efficiently:
async function checkBulkCancellations(cancelIds, headers) {
const results = {};
// Check all cancellations in parallel
const promises = cancelIds.map(async (id) => {
const response = await fetch(
`https://app.masonhub.co/{account}/api/v1/order_cancel_requests?id=${id}`,
{ headers }
);
const data = await response.json();
return { id, data };
});
const responses = await Promise.all(promises);
// Organize results by status
responses.forEach(({ id, data }) => {
if (data.cancel_requests && data.cancel_requests.length > 0) {
const status = data.cancel_requests[0].status;
if (!results[status]) results[status] = [];
results[status].push(data.cancel_requests[0]);
}
});
return results;
}
// Usage
const cancelIds = ["id1", "id2", "id3"];
const statusGroups = await checkBulkCancellations(cancelIds, headers);
console.log(`Successful: ${statusGroups.success?.length || 0}`);
console.log(`Failed: ${statusGroups.failed?.length || 0}`);
console.log(`Pending: ${statusGroups.pending?.length || 0}`);
Best Practices
Use Webhooks
Configure orderCancelResolution callbacks for instant notifications
Handle Partials
Check cancellation_details for partial cancellations requiring special handling
Track Request IDs
Store system_id from submission for reliable tracking
Implement Retry Logic
Retry failed cancellations with corrected data when appropriate
Cancellation requests older than 30 days may be archived and unavailable. Store important cancellation history in your own system.
Webhook Configuration
For real-time cancellation updates, configure webhooks:
POST /callbacks
{
"callback_url": "https://your-api.com/webhooks/order-cancels",
"event_type": "orderCancelResolution"
}
You’ll receive notifications when cancellations complete:
{
"message_type": "orderCancelResolution",
"data": [
{
"cancel_request_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"customer_identifier": "129374",
"status": "success",
"resolved_at": "2024-01-17T10:31:45Z",
"items_canceled": 2
}
]
}
Combine polling for immediate checks with webhooks for asynchronous notifications. This provides both responsive UI updates and efficient background processing.
Related Endpoints
- Cancel Orders - Submit cancellation requests
- Get Orders - Check current order status
- Order Cancel Resolutions - Webhook configuration
- Create Returns - For already shipped orders
Sources
# Get specific cancellation request by ID
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_cancel_requests?id=7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d" \
-H "Authorization: Bearer your_jwt_token"
# Get all cancellation requests for an order
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_cancel_requests?cid=129374" \
-H "Authorization: Bearer your_jwt_token"
# Get pending cancellation requests
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_cancel_requests?status=pending&limit=50" \
-H "Authorization: Bearer your_jwt_token"
curl --request GET \
--url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/order_cancel_requests \
--header 'Authorization: Bearer <token>'{
"total_count": 2,
"limit": 100,
"offset": 0,
"cancel_requests": [
{
"system_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
"customer_identifier": "129374",
"status": "success",
"reason": "customer_request",
"notes": "Customer changed their mind before shipment",
"requested_by": "customer.service@example.com",
"submitted_at": "2024-01-17T10:30:00Z",
"resolved_at": "2024-01-17T10:31:45Z",
"processing_time_ms": 1450,
"cancellation_details": {
"items_canceled": 2,
"inventory_released": true,
"order_status_before": "processing",
"order_status_after": "canceled",
"refund_required": true
}
},
{
"system_id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
"customer_identifier": "129375",
"status": "failed",
"reason": "customer_request",
"notes": "Attempted cancellation after shipment",
"requested_by": "support@example.com",
"submitted_at": "2024-01-17T11:00:00Z",
"resolved_at": "2024-01-17T11:00:05Z",
"processing_time_ms": 50,
"error": {
"code": "ORDER_ALREADY_SHIPPED",
"message": "Cannot cancel order that has been shipped",
"details": {
"order_status": "fulfilled",
"shipped_at": "2024-01-17T09:00:00Z",
"tracking_number": "1Z999AA10123456784"
}
}
}
]
}