Skip to main content
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.
FieldTypeNotes
urltext
typetextNullable; "icon" for icons, null for gallery images
is_thumbnailbooleanDefault false
is_bannerbooleanDefault false
ranknumberDefault 0; gallery ordering
metadatajsonNullable
Ownership lives in the link table, not on the record — the same module serves any linked entity.
LinkAliasPurpose
Product.productCategory ↔ MediaImagemedia_imagesCategory gallery + icon
Product.productCollection ↔ MediaImagemedia_imagesCollection 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.
  • 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

Workflows

Admin API