# 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`.

```json
{
  "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.

```json
{
  "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
```