> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media module

> Image records for categories and collections — galleries, thumbnails, banners, and icons.

The Media module owns generic image records attached to marketplace entities through module links. It powers the media galleries on **product categories** and **product collections**, including thumbnail, banner, and icon designations.

The model is deliberately named `MediaImage` (table `media_image`) to avoid colliding with Medusa's product `Image` model.

## Data models

### `MediaImage`

Table `media_image`, ID prefix `medimg`.

| Field          | Type    | Notes                                                   |
| -------------- | ------- | ------------------------------------------------------- |
| `url`          | text    |                                                         |
| `type`         | text    | Nullable; `"icon"` for icons, `null` for gallery images |
| `is_thumbnail` | boolean | Default `false`                                         |
| `is_banner`    | boolean | Default `false`                                         |
| `rank`         | number  | Default `0`; gallery ordering                           |
| `metadata`     | json    | Nullable                                                |

Ownership lives in the link table, not on the record — the same module serves any linked entity.

## Links

| Link                                       | Alias          | Purpose                   |
| ------------------------------------------ | -------------- | ------------------------- |
| `Product.productCategory` ↔ `MediaImage`   | `media_images` | Category gallery + icon   |
| `Product.productCollection` ↔ `MediaImage` | `media_images` | Collection gallery + icon |

## Invariants

The service is plain CRUD; the invariants are enforced by the `setCategoryImagesWorkflow` / `setCollectionImagesWorkflow`:

* At most **one thumbnail**, **one banner**, and **one icon** per entity.
* The same image may be both thumbnail and banner.
* Setting `icon: null` clears the icon; deleting the entity removes its linked images (no orphans).

Create/update/delete of categories and collections goes through thin wrapper workflows (`createProductCollectionWithImagesWorkflow`, etc.) that combine Medusa's core workflow with the image-set step.

## Related endpoints

* `GET/POST/DELETE /admin/collections[/:id]` — accept `media[]` (with thumbnail/banner designations) and `icon` in the body; responses include the linked `images`.
* Admin product-category routes accept the same shape.
* Vendor collection and category routes expose the images read-only.

## Next steps

<CardGroup cols={2}>
  <Card title="Workflows" href="/rc/references/workflows" />

  <Card title="Admin API" href="/rc/references/api/admin" />
</CardGroup>