1. Orders
  2. Get Order Cancels
GET
/order_cancel_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:

id
string

Filter by cancellation request system ID (UUID). Returns specific cancellation request.

cid
string

Filter by customer identifier. Returns all cancellation requests for a specific order.

status
string

Filter by request status:

  • pending - Awaiting processing
  • processing - Currently being processed
  • success - Cancellation completed
  • failed - Cancellation failed
  • partial - Some items canceled, others not
limit
default:100
integer

Maximum number of records to return (1-1000).

offset
default:0
integer

Number of records to skip for pagination.

created_after
string

Filter requests created after this timestamp (RFC3339 format).

created_before
string

Filter requests created before this timestamp (RFC3339 format).

resolved_after
string

Filter requests resolved after this timestamp (RFC3339 format).

resolved_before
string

Filter requests resolved before this timestamp (RFC3339 format).

reason
string

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

system_id
string

Unique identifier for the cancellation request

customer_identifier
string

Your order reference ID

status
string

Current status of the cancellation request:

  • pending - Queued for processing
  • processing - Currently being canceled
  • success - Cancellation completed
  • failed - Cancellation could not be completed
  • partial - Some items canceled, others not
reason
string

Cancellation reason code provided in request

notes
string

Additional context provided with cancellation

requested_by
string

Identifier of person/system that requested cancellation

submitted_at
string

Timestamp when cancellation was requested

resolved_at
string

Timestamp when processing completed (null if pending)

processing_time_ms
integer

Time taken to process the cancellation in milliseconds

cancellation_details
object

Detailed information about the cancellation:

  • items_canceled - Number of items successfully canceled
  • inventory_released - Whether inventory was released
  • order_status_before - Order status before cancellation
  • order_status_after - Order status after cancellation
  • refund_required - Whether refund processing is needed
error
object

Error details if cancellation failed

​
Cancellation Request Lifecycle

Track cancellation requests through their processing stages:

1

pending

Request received and queued for processing

2

processing

System actively canceling the order:

  • Stopping fulfillment processes
  • Releasing inventory allocations
  • Updating order status
3

Resolution

Final status determined:

  • success - Order fully canceled
  • failed - Cancellation not possible
  • partial - 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

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.

​
Sources