Order Cancellations

Manages order and bag cancellations. Use these endpoints to cancel orders, bags, and retrieve cancellation information.

Overview

Only unfulfilled bags qualify for cancellation. A bag must be in one of the following statuses: ACCEPTED, SUBMITTED, COMPLETED, or PARTIALLY_REFUNDED. When a cancellation succeeds on the merchant's platform, Violet automatically processes a full refund for the bag.

You can cancel at two levels:

• Order-level — POST /orders/{order_id}/cancel sends a cancellation request for every eligible bag in the order.

• Bag-level — POST /orders/{order_id}/bags/{bag_id}/cancel cancels a single bag.

Cancellation Request

Each cancellation request accepts the following options:

Field	Default	Description
reason	—	Custom message describing the reason for the cancellation.
reason_code	OTHER	Code that best represents the reason. One of OTHER, CUSTOMER, INVENTORY, FRAUD, or DECLINED.
restock_items	true	Whether the items should be restocked on the merchant's platform.
notify_customer	false	Whether the merchant's platform should send the customer a cancellation notification.

Cancellation Status

Use the status field on the OrderCancellation response to determine the overall outcome.

Status	Description
CANCELED	All bags were successfully canceled.
PARTIALLY_CANCELED	Some bags were canceled; others failed.
CANCELLATION_FAILURE	All bag cancellations failed.

Each entry in the cancelled_bags array carries its own status:

Status	Description
CANCELED	The bag was successfully canceled on the merchant's platform.
CANCELLATION_FAILURE	The cancellation failed on the merchant's platform. Check the errors array for details.

Determine Cancellation Outcome

Use the status and cancelled_bags fields on the OrderCancellation response to understand what happened.

Successful Cancellation

When all bags are canceled, the response status is CANCELED and each bag entry includes an associated refund.

{
  "order_id": 987654321,
  "status": "CANCELED",
  "cancelled_bags": [
    {
      "bag_id": 123456789,
      "status": "CANCELED",
      "originated_by": "CHANNEL",
      "date_cancelled": "2024-10-24T14:00:39.000+00:00",
      "refund": {
        "reason": "Order canceled"
      }
    }
  ],
  "message": "All external orders were cancelled."
}

Partial or Failed Cancellation

When one or more bags fail, the response status is PARTIALLY_CANCELED or CANCELLATION_FAILURE. Inspect the errors array on each failed bag for details.

{
  "order_id": 987654321,
  "status": "CANCELLATION_FAILURE",
  "cancelled_bags": [
    {
      "bag_id": 123456789,
      "status": "CANCELLATION_FAILURE",
      "originated_by": "CHANNEL",
      "date_cancelled": "2024-10-24T14:00:39.000+00:00",
      "errors": [
        {
          "type": "EXTERNAL_CANCEL_ORDER",
          "message": "Paid and fulfilled bags cannot be cancelled."
        }
      ]
    }
  ],
  "message": "All external orders failed to be cancelled."
}

Originator

The originated_by field on each bag cancellation record indicates who initiated the cancellation:

Value	Description
CHANNEL	The cancellation was initiated by your application via the API.
MERCHANT	The merchant canceled the bag from their own platform.
VIOLET	Violet canceled the bag automatically (e.g., during order processing).

---

Available endpoints:

POST /v1/orders/{order_id}/cancel
POST /v1/orders/{order_id}/bags/{bag_id}/cancel
 GET /v1/orders/{order_id}/cancellations