> 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/products/product-images.md).

# Product Images

Administrative endpoints for **product images** — the image records attached to a catalog product, the order in which they are shown, and their promotion to a special role such as the product's main image.

### Core Capabilities

**1. Image Listing & Filtering**

* Retrieve a paginated list of product images.
* Filter by the product an image belongs to, or by the exact stored path of an image.
* Results are ordered by display order ascending by default; use the `sort` query parameter to order by another of the returned fields.

**2. Image Creation**

* Add an image to a product either by sending the file content itself, or by referencing a file that is already present in the platform's media storage.
* Place the image within the product's gallery through its display order, which is required on create.

**3. Image Maintenance**

* Retrieve a single image, change its display order or the stored file it points to, or delete it.

**4. Special Image Assignment**

* Promote an existing image to one of the roles listed under **Special Image Types**. A product holds at most one image per role, so assigning a role replaces the image that previously held it for that product.

### Supplying the Image

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

| Field        | When to use it                                                                                 | Additional requirements                                                                                                                                                                                                                     |
| ------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`      | You are sending the file content itself, as text, in the request.                              | None, but the stored record will carry no dimensions. The file name and storage location are generated by the platform, and `height` and `width` are always taken from the stored file rather than from the request — see the caveat below. |
| `image_path` | The file is already present in the platform's media storage and you only want to reference it. | `height` and `width` must both be sent in the same request, because they cannot be derived from a file that is only referenced.                                                                                                             |

If neither field is supplied, or `image_path` is supplied without both `height` and `width`, the request is rejected with the business error `product_image_500_1`.

Sending both fields is not an error, but it is not useful either: `image` takes precedence and `image_path` is ignored. The `height` and `width` requirement still applies in that case, because `image_path` is present — so a request carrying both fields without dimensions is rejected even though the path would have been ignored. Send only the field you mean to use.

> **Caveat on `image`.** This field is a **text** field, not a binary file upload: its value is written to storage verbatim as the file's content. Because such content is not a decodable image, the platform cannot measure it, and the created record is stored with `height` and `width` set to `null` — any dimensions you send alongside `image` are discarded. To register an image whose dimensions are recorded, upload the file to the media storage by other means and reference it with `image_path`, supplying `height` and `width` yourself.

Stored files are placed under a dated, per-product location in the configured media storage. The stored file name is generated by the platform and is never taken from the request.

`image_path` is accepted in requests only. It is never returned in a response — responses report the resulting stored path in `image`.

### Display Order

`order` positions the image within the product's gallery; lower values are shown first. It is **required on create** — there is no default to fall back on, so send it with every create request. On update it is optional: an omitted field is left unchanged.

### Special Image Types

| Value     | Description                                             |
| --------- | ------------------------------------------------------- |
| `base`    | The product's main image.                               |
| `swatch`  | The color or pattern swatch shown in variant selection. |
| `listing` | The image used on listing and category pages.           |
| `picto`   | A pictogram or badge shown alongside the product.       |

### Marketplace Offer Propagation

When an image belongs to a **seller product**, changes are mirrored onto that product's offers automatically:

* **Creating** an image copies it to every offer of the product.
* **Updating** an image applies the same changes to the matching offer image, and creates a copy for any offer that does not have one yet.
* **Deleting** an image removes the matching image from every offer of the product.

No propagation takes place for products that are not seller products.

### Listability Side Effects

Whether a product has an **active** image is one of the inputs to its listability. Two operations therefore trigger a listability recalculation across the product's variant group:

* **Creating** an image for a product that had no active image before.
* **Deleting** an image when the product is left with no active image.

Adding or removing an image while the product still has other active images does not trigger a recalculation. When a recalculation runs, the product's last-modified timestamp is also refreshed unless it was already updated within the last minute.

When `omnishop.products.listable_rules.all_variants_have_image_rule` is the **first** entry of `LISTABLE_PRODUCT_RULES`, the recalculation is evaluated for the variant group as a whole: deleting the last active image of one variant leaves the **entire** group without a listable product, and creating that missing image again makes the group listable. Under the default rules a single variant with an image is enough to keep the group listable.

Every image created through these endpoints is active — the status of an image is not part of this API and cannot be set or changed here. A product may still carry images that were disabled elsewhere in the platform; those do not count towards the checks above.

### Dynamic Settings & Environment Variables

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

| Key                           | Type             | Default                                                                                                | Effect                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LISTABLE_PRODUCT_RULES`      | array of strings | `["omnishop.products.listable_rules.image_rule", "omnishop.products.listable_rules.is_listable_rule"]` | The ordered list of rules that decide which variant becomes the listable product within a group. Affects the listability recalculation triggered by **create** (`POST /product_image/`) and **delete** (`DELETE /product_image/{id}/`) described under **Listability Side Effects**. Each entry must be one of the exact values listed below, and the list cannot be empty. |
| `LIST_SIMPLE_INSTEAD_OF_META` | boolean          | `false`                                                                                                | When enabled, an individual simple variant is exposed as the listable product for its group instead of the parent product meta. Affects the same listability recalculation triggered by **create** and **delete**. When unset, its value falls back to the corresponding server configuration value, and to `false` if that is also unset.                                  |

These are the only values `LISTABLE_PRODUCT_RULES` accepts. Each must be given in full, exactly as written; abbreviated names such as `image_rule` are rejected.

| Value                                                           | Chooses the variant that                                                                                                                                                                      |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `omnishop.products.listable_rules.image_rule`                   | has an image                                                                                                                                                                                  |
| `omnishop.products.listable_rules.is_listable_rule`             | is already listable                                                                                                                                                                           |
| `omnishop.products.listable_rules.stock_rule`                   | has stock, in its own or an additional stock list                                                                                                                                             |
| `omnishop.products.listable_rules.all_stock_rule`               | has stock in every stock list                                                                                                                                                                 |
| `omnishop.products.listable_rules.all_variants_have_image_rule` | belongs to a group in which **every** active variant has an image; if a single one has none, no variant of the group is chosen. Place it as the first entry of the list for it to take effect |
| `omnishop.products.listable_rules.max_price_rule`               | has the highest price                                                                                                                                                                         |
| `omnishop.products.listable_rules.min_price_rule`               | has the lowest price                                                                                                                                                                          |

**Environment variables:** No environment variables are read directly by these endpoints. The only related server configuration values are the platform's media storage configuration, which determines where uploaded image files are stored, and the fallback value of `LIST_SIMPLE_INSTEAD_OF_META` described above.


---

# 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/products/product-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.
