> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/orders/cancellation-requests.md).

# Cancellation Requests

Administrative endpoints for **cancellation requests** — requests to cancel (before shipment) or return (after shipment) a single order item. Customers open these requests on the storefront; Omnitron uses these endpoints to list them, move them through their lifecycle and reject easy-return requests.

Every endpoint identifies a cancellation request by its `uuid`, not by its numeric `id`. Requests that belong to an order whose status is `200` (`waiting`) — an order whose payment has not been confirmed yet — are hidden from every operation: they are not listed, and retrieving, updating, deleting or rejecting them answers with `404`.

### Core Capabilities

**1. Listing & Filtering**

* Retrieve a paginated list of cancellation requests.
* Filter by status, type, reason, order item, easy-return record, IBAN, holder name, description, quantity, loyalty refund flag, `uuid`, and creation or modification date.
* Order results with the `sort` parameter. Without `sort` the results are returned in **random order**; send `sort` to get the same order on every page.

**2. Retrieval**

* Retrieve a single cancellation request with its reason, easy-return record and images embedded.
* `/cancellation_requests/{uuid}/detailed/` returns the same representation as the retrieve operation.

**3. Lifecycle Update**

* Update a request's `status` or move it to another `order_item`. These are the only two fields that are saved; the other fields in the request body are validated and left unchanged.
* Any status value can be set directly. No notification is sent for an update.

**4. Easy-Return Rejection**

* Reject an easy-return (refund) request with `POST /cancellation_requests/{uuid}/reject_cancellation/`. The return code is cancelled at the carrier and the rejection is forwarded to Omnitron.

**5. Creation**

* Create a single request or several requests of one order at once (`/bulk_create/`).
* Creation always happens **on behalf of the authenticated account**: the order item must belong to an order of that account; otherwise the request is rejected with `406` (`cancellation_request_100_2`). An administrator therefore cannot open a request for a customer's order item through these endpoints.

**6. Deletion**

* Delete a cancellation request. Deletion is permanent.

### Request Statuses

| Value                  | Description                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `open`                 | The request has been created and not yet processed. New requests always start here.                     |
| `waiting`              | The request is waiting to be processed.                                                                 |
| `confirmation_waiting` | The request is waiting for confirmation.                                                                |
| `confirmed`            | The request has been confirmed.                                                                         |
| `waiting_approval`     | The request is waiting for approval.                                                                    |
| `approved`             | The request has been approved.                                                                          |
| `rejected`             | The request has been rejected. A rejected request does not block a new request for the same order item. |
| `waiting_for_payment`  | The refund payment is pending.                                                                          |
| `manuel_refund_need`   | The refund must be made manually.                                                                       |
| `completed`            | The request has been completed.                                                                         |

### Request Types

| Value    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cancel` | Cancels an order item that has not been shipped. The item must be in a status between `200` (`waiting`) and `450` (`preparing`) and must not have an invoice number; otherwise the request is rejected with `406` (`cancellation_request_100_6`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `refund` | Returns an order item, typically after it has been shipped. An easy-return record (a return code at a carrier) is created with the request when the site's easy-return configuration allows it. If the code cannot be created (for example the carrier service fails), the request is not created and the whole create request is rolled back with `406`: the carrier integration's own error code is returned when it reports one (e.g. `yurtici_easy_return_100`), otherwise `cancellation_request_100_11`; the customer can send the request again. Only when `CREATE_CANCELLATION_WITHOUT_EASY_RETURN_ON_ERROR` is `true` is the error logged and the request created without an easy-return record (`easy_return` is `null`). |

### Creation Rules

A create request is rejected when one of the following rules is not met.

| # | Rule                                                                                                                                                                          | Response                           |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| 1 | The order item belongs to an order of the authenticated account.                                                                                                              | `406` `cancellation_request_100_2` |
| 2 | The order item is not cancelled or refunded already.                                                                                                                          | `406` `cancellation_request_100_3` |
| 3 | For `cancel`, the order item can still be cancelled (see **Request Types**).                                                                                                  | `406` `cancellation_request_100_6` |
| 4 | The order item has no other request that is not `rejected`.                                                                                                                   | `406` `cancellation_request_100_1` |
| 5 | When IBAN collection is enabled (`CANCELLATION_REQUEST_IBAN_NUMBER_REQUIRED`) and the order was paid by funds transfer or pay on delivery, `iban` and `holder_name` are sent. | `406` `cancellation_request_100_5` |
| 6 | When the reason requires extra information, `description` is sent.                                                                                                            | `406` `cancellation_request_100_4` |
| 7 | For `refund`, when a pickup address is required (`CANCELLATION_REQUEST_ADDRESS_REQUIRED`), `pickup_address` is sent.                                                          | `406` `cancellation_request_100_8` |
| 8 | Products that cannot be sold alone and their main product are cancelled together (`OFFER_MISCELLANEOUS_ATTRIBUTE_KEY`).                                                       | `406` `cancellation_error_108`     |

The following field checks answer with `400`:

* `shipping_company` is required for `refund` when customers choose the carrier (`EASY_RETURN_PACKAGE_STRATEGY`), and must be an active easy-return shipping company.
* `pickup_address` must be an active customer address of the authenticated account.
* `quantity` must be at least `1`. For products whose order items can be merged (`ATTRIBUTE_KEY_FOR_MERGEABLE_ORDER_ITEM`), it may not exceed the ordered quantity and is stored on the request; for other products it is not stored and is returned as `null`.
* The number, dimensions and file size of the images are limited (see **Dynamic Settings & Environment Variables**).

### Customer Notifications

After a request is created, the following messages are sent to the customer:

| Message                                            | When                                                                                                                                                  |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cancellation SMS and e-mail                        | Scheduled 30 seconds after the request. Further requests of the same type for the same order within these 30 seconds do not schedule another message. |
| Notification-gateway message                       | Scheduled the same way, only when `NOTIFICATION_GATEWAY` is set.                                                                                      |
| Order status notification (`cancellation_waiting`) | Queued immediately, only when `PUSH_NOTIFICATION_ACTIVE` is on.                                                                                       |

`/bulk_create/` sends these messages only for `refund` items.

### Easy-Return Rejection

A request can be rejected only when all of the following are true; otherwise the response is `406` (`cancellation_request_100_9`):

* its type is `refund`,
* its status is `open` or `waiting`,
* it has an easy-return record linked to an easy-return shipping provider.

On success the request becomes `rejected`. The return code is cancelled at the carrier and the easy-return record becomes `cancelled`, unless another `open` or `waiting` request still shares the same return code — then the code is kept. If the carrier does not support remote cancellation, the code is cancelled on the Commerce side only. If the carrier fails to cancel the code, the rejection fails with `406` (`cancellation_request_100_9`) and nothing is changed.

The rejection is forwarded to Omnitron asynchronously after the response is sent.

### Filtering & Ordering

| Parameter                                  | Match                          | Notes                                                                                                                 |
| ------------------------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `status`                                   | Exact                          | One of the values under **Request Statuses**; any other value is rejected with `400`.                                 |
| `cancellation_type`                        | Exact                          | `cancel` or `refund`.                                                                                                 |
| `uuid`                                     | Exact                          | An invalid UUID is rejected with `400`.                                                                               |
| `reason`, `order_item`, `easy_return`      | Exact identifier               | An identifier that does not exist is rejected with `400`.                                                             |
| `iban`, `holder_name`                      | Case-insensitive partial match | Send `NULL_VALUE` to return only requests where the field is empty, or `NOT_NULL_VALUE` for requests where it is set. |
| `description`                              | Exact                          | Partial values do not match.                                                                                          |
| `quantity`                                 | Exact                          |                                                                                                                       |
| `fully_refund_as_loyalty_money`            | Exact                          | `true` or `false`.                                                                                                    |
| `created_date`, `modified_date`            | Exact                          | ISO 8601 date-time.                                                                                                   |
| `modified_date__gte`, `modified_date__lte` | Range                          | ISO 8601 date or date-time.                                                                                           |

Parameters that are not listed here — including `id` and `created_date__gte` — are ignored. Use the `sort` query parameter to order the results; prefix with `-` for descending.

### Dynamic Settings & Environment Variables

The settings below affect only the create, bulk create and reject operations, except where noted. They do not change list, retrieve, update or delete responses.

**Dynamic settings** (`dj_dynamic_settings`):

| Key                                                   | Type                                                                                                                                                 | Default                                                                      | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CANCELLATION_REQUEST_ADDRESS_REQUIRED`               | boolean                                                                                                                                              | `false` (or the Django setting of the same name when defined)                | When `true`, `refund` requests must include `pickup_address`; otherwise they are rejected with `406` (`cancellation_request_100_8`). The address must be an active customer address of the authenticated account. Affects `POST /cancellation_requests/` and `/bulk_create/`.                                                                                                                                                                                                                             |
| `EASY_RETURN_PACKAGE_STRATEGY`                        | string, one of `omnishop.orders.strategies.RuleBasedEasyReturnPackageStrategy`, `omnishop.orders.strategies.SelectionBasedEasyReturnPackageStrategy` | `omnishop.orders.strategies.RuleBasedEasyReturnPackageStrategy`              | How the carrier of an easy return is chosen. With the rule-based strategy the carrier is picked by product rules and `shipping_company` is optional. With the selection-based strategy the customer chooses the carrier, so `refund` requests without `shipping_company` are rejected with `400`. Affects `POST /cancellation_requests/` and `/bulk_create/`.                                                                                                                                             |
| `CANCELLATION_REQUEST_MAX_IMAGE_COUNT_PER_ORDER_ITEM` | integer                                                                                                                                              | `3`                                                                          | The maximum number of images in `cancellation_request_image_set` per order item. More images are rejected with `400`.                                                                                                                                                                                                                                                                                                                                                                                     |
| `MAX_IMAGE_DIMENSIONS`                                | object `{"width": integer, "height": integer}`                                                                                                       | `{"width": 2000, "height": 2000}`                                            | Images must be smaller than these dimensions in pixels; an image whose width or height reaches the limit is rejected with `400`.                                                                                                                                                                                                                                                                                                                                                                          |
| `OFFER_MISCELLANEOUS_ATTRIBUTE_KEY`                   | string                                                                                                                                               | `cannot_be_sold_alone` (or the Django setting of the same name when defined) | The product attribute that marks an offer product as not sellable on its own. Such an item cannot be cancelled without its main product, and a main product cannot be cancelled without all such items attached to it; either case is rejected with `406` (`cancellation_error_108`). Use `/bulk_create/` to cancel them together.                                                                                                                                                                        |
| `THROTTLING_SETTINGS`                                 | object                                                                                                                                               | `{}` (or the Django setting of the same name when defined)                   | Per-scope rate limits. The `cancellation-request-bulk-create` scope limits `/bulk_create/` per authenticated account; the built-in default is `{"count": 1, "duration": 5}` (1 request per 5 seconds). One request over the limit is tolerated; further requests are rejected with `429`. Requests are counted whether or not they succeed.                                                                                                                                                               |
| `ATTRIBUTE_KEY_FOR_MERGEABLE_ORDER_ITEM`              | string                                                                                                                                               | `allow_mergeable_order_item`                                                 | The product attribute that marks products whose order items can be merged. For these products (when their stock unit is quantity), `quantity` is stored on the request and may not exceed the ordered quantity; for other products `quantity` is ignored and returned as `null`.                                                                                                                                                                                                                          |
| `NOTIFICATION_GATEWAY`                                | string                                                                                                                                               | `""` (or the Django setting of the same name when defined)                   | When empty, no notification-gateway message is scheduled after a request is created. SMS and e-mail are scheduled regardless; their delivery follows the gateway and e-mail settings listed in the **Orders** section.                                                                                                                                                                                                                                                                                    |
| `PUSH_NOTIFICATION_ACTIVE`                            | boolean                                                                                                                                              | `false` (or the Django setting of the same name when defined)                | When `true`, an order status notification (`cancellation_waiting`) is queued after a request is created.                                                                                                                                                                                                                                                                                                                                                                                                  |
| `CREATE_CANCELLATION_WITHOUT_EASY_RETURN_ON_ERROR`    | boolean                                                                                                                                              | `false`                                                                      | What happens when the easy-return code of a `refund` request cannot be created. When `false`, nothing is saved and the request is rejected with `406` (the carrier integration's own error code, e.g. `yurtici_easy_return_100`, or `cancellation_request_100_11`); in `/bulk_create/` the whole request is rolled back. When `true`, the error is logged and the request is created without an easy-return record (`easy_return` is `null`). Affects `POST /cancellation_requests/` and `/bulk_create/`. |

**Environment variables / Django settings:**

| Setting                                     | Default               | Effect                                                                                                                                                                                   |
| ------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CANCELLATION_REQUEST_IBAN_NUMBER_REQUIRED` | `false` (not defined) | When `true`, requests for orders paid by funds transfer or pay on delivery must include `iban` and `holder_name`; otherwise they are rejected with `406` (`cancellation_request_100_5`). |
| `FILE_UPLOAD_MAX_MEMORY_SIZE`               | `5242880` (5 MB)      | The maximum size of a single image in `cancellation_request_image_set`. Larger images are rejected with `400`.                                                                           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/orders/cancellation-requests.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
