Cancellation Reasons

Overview

When cancelling an order through our API, you must provide a reason for the cancellation. This helps with order tracking, reporting, and customer service.

Available Cancellation Reasons

When setting an order status to cancelled, you must include one of the following cancellation reasons:

Channel-Specific Cancellation Reasons

The cancellation reasons listed above are the standard base reasons supported across all channels. However, depending on your specific integration channel (e.g., Salesforce, Shopify, etc.), additional channel-specific cancellation reasons may be available.

If you're working with a specific channel and need information about additional supported cancellation reasons, please refer to your channel-specific documentation or contact Naveo Support at gsd@maginus.atlassian.net.

How to Use Cancellation Reasons

When cancelling an order, include the cancellation reason in the request body:

PATCH /v1/orders/{orderId}/status
{
  "status": "cancelled",
  "metadata": {
    "cancellation_reason": "customer_requested",
    "notes": "Customer changed their mind"
  }
}

Required Fields

When cancelling an order:

• The status field must be set to cancelled
• The metadata.cancellation_reason field must be included with one of the valid cancellation reason codes
• The metadata.notes field is optional but recommended to provide additional context

Error Handling

If you attempt to cancel an order without providing a cancellation reason, the API will return a 400 error:

{
  "error": "Missing required field",
  "message": "A cancellation_reason is required when status is cancelled",
      "valid_reasons": ["customer_requested", "customer_request", "customer_service", "customer_no_show"]
}

If you provide an invalid cancellation reason, the API will also return a 400 error:

{
  "error": "Invalid cancellation reason",
  "message": "Reason must be one of: customer_requested, customer_request, customer_service, customer_no_show"
}

Best Practices

• Always provide the most accurate cancellation reason
• Include helpful notes that explain the specific circumstances
• For customer-initiated cancellations, consider capturing the specific reason from the customer (e.g., "found a better price elsewhere") in the notes field