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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/api-reference/orders-and-checkout/order-cancellations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.