> 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-request-images.md).

# Cancellation Request Images

Administrative endpoints for **cancellation request images** — the images attached to a cancellation or refund request of an order item.

A cancellation request image belongs to exactly one cancellation request and carries the stored image file, an optional free-text description, free-form `attributes`, and a flag telling whether the customer or an administrator uploaded it. Customers attach images while creating a cancellation request on the storefront; these endpoints let Omnitron and integration systems read those images and add, change, or remove images on behalf of the platform.

### Core Capabilities

**1. Image Listing & Filtering**

* Retrieve a paginated list of cancellation request images, ordered by ascending identifier.
* Filter by cancellation request, description, uploader, or last-modified date range.
* Order results with the `sort` parameter, as described under **Filtering & Ordering**.

**2. Image Creation**

* Attach an image to a cancellation request either by sending the file content encoded as base64, or by referencing a file that is already present in the platform's media storage.

**3. Image Maintenance**

* Retrieve a single image, change its description, attributes, the cancellation request it belongs to, or the stored file it points to, or delete it.

### Cancellation Request Image Fields

| Field                  | Type               | Description                                                                                                                                                                                 |
| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | integer            | The unique identifier of the image. Assigned by the server; read-only.                                                                                                                      |
| `cancellation_request` | string (UUID)      | The `uuid` of the cancellation request the image belongs to — **not** its numeric identifier. Required on create and full update.                                                           |
| `image`                | string             | On **write**, the base64-encoded file content (see **Supplying the Image**). On **read**, the absolute URL of the stored file.                                                              |
| `image_path`           | string             | **Write-only.** Path of a file already present in the platform's media storage. Never returned in a response.                                                                               |
| `description`          | string or `null`   | Optional free-text description of the image. Defaults to `null`.                                                                                                                            |
| `attributes`           | object or `null`   | Optional free-form JSON object. Defaults to `{}`. Replaced as a whole on update, not merged.                                                                                                |
| `is_uploaded_by_user`  | boolean            | Read-only. `true` when the customer attached the image through the storefront cancellation flow; `false` for every image created or updated through these endpoints. See **Uploader Flag**. |
| `created_date`         | string (date-time) | Read-only. When the record was created.                                                                                                                                                     |
| `modified_date`        | string (date-time) | Read-only. When the record was last changed.                                                                                                                                                |

### Supplying the Image

A create request supplies the image in one of two ways.

| Field        | When to use it                                                                                 | Validation                                                                                                                                                                                                                                                                                                                 |
| ------------ | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`      | You are sending the file content itself.                                                       | The value must be a **base64** string, with or without a `data:image/<type>;base64,` prefix, decoding to a `jpeg`, `jpg`, `png`, `gif` or `webp` image. The decoded file must not exceed `FILE_UPLOAD_MAX_MEMORY_SIZE` and its width and height must both be **strictly lower** than the limits in `MAX_IMAGE_DIMENSIONS`. |
| `image_path` | The file is already present in the platform's media storage and you only want to reference it. | None. The path is stored as sent; the platform does **not** check that the file exists, nor its size, type or dimensions.                                                                                                                                                                                                  |

If neither field is supplied, the request is rejected with `406 Not Acceptable` and the business error `cancellation_request_image_100_1`. If both are supplied, `image` takes precedence and `image_path` is ignored.

Files sent in `image` are stored under `cancellation_request_images/{YYYY}/{MM}/{DD}/` with a generated UUID file name. The stored name always ends in `.jpg`, whatever the actual image format; the content itself is stored unchanged.

### Update Semantics

* **The file content cannot be replaced.** `image` is still validated on `PUT` / `PATCH` — an invalid value is rejected with `400` — but a valid value is discarded and the stored file is left unchanged. To point the record at a different file, send its path in `image_path`.
* **`cancellation_request` can be changed.** Sending another request's `uuid` moves the image to that cancellation request.
* `PUT` requires `cancellation_request`; every other field is optional, and fields left out keep their current value. `PATCH` requires nothing.
* `attributes` is replaced with the submitted object, and `null` is accepted.
* `is_uploaded_by_user` is ignored if sent — see **Uploader Flag**.

### Uploader Flag

`is_uploaded_by_user` distinguishes images uploaded by customers from images added by administrators. Images attached by customers through the storefront cancellation flow are stored with `true`. Every image created **or updated** through these endpoints is stored with `false`: the field is read-only here, and the value is forced to `false` on each write. As a consequence, updating a customer-uploaded image through `PUT` or `PATCH` flips it to `false`.

### Filtering & Ordering

| Parameter                                  | Match                 | Notes                                                                                                                                                                                                 |
| ------------------------------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cancellation_request`                     | Exact                 | The numeric identifier of the cancellation request — **not** its `uuid`, even though requests and responses carry the `uuid`. A `uuid`, or an identifier that does not exist, is rejected with `400`. |
| `description`                              | Exact, case-sensitive | There is no partial or case-insensitive variant.                                                                                                                                                      |
| `is_uploaded_by_user`                      | Boolean               | `true` returns customer-uploaded images, `false` those created or updated through these endpoints. A value other than `true` / `false` / `1` / `0` is ignored.                                        |
| `modified_date`                            | Exact                 | ISO 8601 date-time.                                                                                                                                                                                   |
| `modified_date__gte`, `modified_date__lte` | Range                 | ISO 8601 date-time, inclusive. A date without a time (e.g. `2026-09-30`) is rejected with `400`.                                                                                                      |

Appending `!` to a parameter name excludes the matching records instead of selecting them — `?cancellation_request!=12` returns every image that does **not** belong to cancellation request `12`. Filters are combined with AND. Any other query parameter, including `id` and `created_date`, is ignored rather than rejected.

When a date-time carries a UTC offset, URL-encode the `+` sign as `%2B` (or use the `Z` suffix), otherwise it is read as a space and the value is rejected.

Without a `sort` parameter, results are ordered by ascending `id`. Use `sort` to order on `id`, `pk`, `cancellation_request`, `image`, `description`, `attributes`, `is_uploaded_by_user`, `created_date` or `modified_date`; prefix a field with a hyphen for descending order (e.g. `?sort=-created_date`). Unrecognised `sort` values are silently ignored.

### Deletion Behavior

`DELETE /cancellation_request_images/{id}/` **permanently removes** the record. The cancellation request itself is not affected. Deleting a cancellation request deletes its images along with it.

### Dynamic Settings & Environment Variables

The behavior of these endpoints is influenced by the following dynamic setting, configured in the management panel. It is referenced again in the description of the operations it affects.

| Key                    | Type                     | Default                           | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MAX_IMAGE_DIMENSIONS` | object `{width, height}` | `{"width": 2000, "height": 2000}` | Upper bounds, in pixels, for the file sent in `image`. Both keys are required and must be integers greater than or equal to `0`. An image whose width is greater than or equal to `width`, or whose height is greater than or equal to `height`, is rejected with `400` on the `image` field. The error message always quotes the `width` value, even when it was the height that exceeded the limit. Affects **create** (`POST /cancellation_request_images/`) and **update** (`PUT` / `PATCH /cancellation_request_images/{id}/`) whenever `image` is sent; it is not applied to `image_path`. Shared with other image uploads of the platform. |

`CANCELLATION_REQUEST_MAX_IMAGE_COUNT_PER_ORDER_ITEM` (integer, default `3`) limits how many images a customer may attach per order item in the storefront cancellation flow. It is **not** enforced by these endpoints — any number of images can be attached to a cancellation request here.

**Deployment settings.** The following Django setting is part of the deployment configuration rather than the management panel, so it cannot be changed at runtime:

| Setting                       | Default          | Effect                                                                                                                                                                                                |
| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FILE_UPLOAD_MAX_MEMORY_SIZE` | `5242880` (5 MB) | Maximum size of the decoded file sent in `image`. A larger file is rejected with `400` on the `image` field. Affects **create** and **update** whenever `image` is sent; not applied to `image_path`. |

**Environment variables:** No environment variables are read directly by these endpoints. The platform's media storage configuration determines where uploaded files are stored and the host of the URL returned in `image`.


---

# 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-request-images.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.
