Catalog data models

The catalog’s data models belong to Medusa’s Product module, version 2.22. Mercur adds no columns to them. It adds relations through module links, listed under each model. Every model also has created_at, updated_at, and deleted_at timestamps that Medusa manages.

Product

The shared master product. Table product, id prefix prod.

Field	Type	Description
`id`	`text`	Primary key
`title`	`text`	Display title, searchable and translatable
`handle`	`text`	URL handle, unique among non-deleted products
`subtitle`	`text`, nullable	Subtitle, searchable and translatable
`description`	`text`, nullable	Description, searchable and translatable
`is_giftcard`	`boolean`	Whether the product is a gift card. Default `false`
`status`	`enum`	`draft`, `proposed`, `published`, or `rejected`. Default `draft`
`thumbnail`	`text`, nullable	Thumbnail image URL
`weight`	`float`, nullable	Weight
`length`	`float`, nullable	Length
`height`	`float`, nullable	Height
`width`	`float`, nullable	Width
`origin_country`	`text`, nullable	Country of origin
`hs_code`	`text`, nullable	Harmonized System code
`mid_code`	`text`, nullable	Manufacturer identification code
`material`	`text`, nullable	Material, translatable
`discountable`	`boolean`	Whether promotions can apply. Default `true`
`external_id`	`text`, nullable	Id in an external system
`metadata`	`json`, nullable	Custom key-value data

Native relations:

variants: ProductVariant[], deleted with the product
options: ProductOption[] through the ProductProductOption pivot
images: ProductImage[], deleted with the product
categories: ProductCategory[] through product_category_product
collection: ProductCollection, nullable
type: ProductType, nullable
tags: ProductTag[] through product_tags

Mercur relations:

sellers: Seller[], the store allowlist in product_seller
product_attribute_values: attribute values attached to the product
scoped_attributes: product-scoped attributes, read-only
changes: ProductChange[], the audit and edit history, read-only
reviews: Review[]

ProductVariant

One purchasable configuration of a product. Table product_variant, id prefix variant.

Field	Type	Description
`id`	`text`	Primary key
`title`	`text`	Display title, searchable and translatable
`sku`	`text`, nullable	Catalog SKU, unique among non-deleted variants
`barcode`	`text`, nullable	Barcode, unique
`ean`	`text`, nullable	EAN, unique
`upc`	`text`, nullable	UPC, unique
`allow_backorder`	`boolean`	Default `false`
`manage_inventory`	`boolean`	Model default `true`; Mercur’s create workflow sends `false`
`hs_code`	`text`, nullable	Harmonized System code
`origin_country`	`text`, nullable	Country of origin
`mid_code`	`text`, nullable	Manufacturer identification code
`material`	`text`, nullable	Material, translatable
`weight`	`float`, nullable	Weight
`length`	`float`, nullable	Length
`height`	`float`, nullable	Height
`width`	`float`, nullable	Width
`thumbnail`	`text`, nullable	Variant thumbnail URL
`variant_rank`	`number`, nullable	Sort order. Default `0`
`metadata`	`json`, nullable	Custom key-value data

Relations: product (nullable), options (ProductOptionValue[] through product_variant_option), and images (ProductImage[]). Mercur links offers to variants through offer.variant_id. Each store’s price and stock live on the offer, not here.

ProductOption

An axis that variants vary on. Table product_option, id prefix opt.

Field	Type	Description
`id`	`text`	Primary key
`title`	`text`	Option name, such as `Size`
`is_exclusive`	`boolean`	`true` when the option belongs to one product. Default `false`
`metadata`	`json`, nullable	Custom key-value data

Relations: products and values (ProductOptionValue[]). A variant-axis attribute mirrors one option through product_attribute.product_option_id.

ProductOptionValue

One value of an option. Table product_option_value, id prefix optval.

Field	Type	Description
`id`	`text`	Primary key
`value`	`text`	The value, such as `M`
`rank`	`number`, nullable	Sort order
`metadata`	`json`, nullable	Custom key-value data

Relations: option (nullable), variants, and product_options.

ProductImage

A product image. Table image, id prefix img.

Field	Type	Description
`id`	`text`	Primary key
`url`	`text`	Image URL
`rank`	`number`	Sort order. Default `0`
`metadata`	`json`, nullable	Custom key-value data

Relations: product and variants.

ProductCategory

A node in the category tree. Table product_category, id prefix pcat.

Field	Type	Description
`id`	`text`	Primary key
`name`	`text`	Display name, searchable and translatable
`description`	`text`	Description. Default `""`
`handle`	`text`	URL handle, unique
`mpath`	`text`	Materialized path of ancestor ids
`is_active`	`boolean`	Whether the category is live. Default `false`
`is_internal`	`boolean`	Hidden from the storefront. Default `false`
`rank`	`number`	Sort order among siblings. Default `0`
`external_id`	`text`, nullable	Id in an external system
`metadata`	`json`, nullable	Custom key-value data

Relations: parent_category (nullable), category_children (deleted with the parent), and products. Mercur adds sellers, media_images, and the product attribute link.

ProductCollection

A flat group of products. Table product_collection, id prefix pcol.

Field	Type	Description
`id`	`text`	Primary key
`title`	`text`	Display title, searchable and translatable
`handle`	`text`	URL handle, unique
`external_id`	`text`, nullable	Id in an external system
`metadata`	`json`, nullable	Custom key-value data

Relations: products. Mercur adds media_images.

ProductTag

A free-form label. Table product_tag, id prefix ptag.

Field	Type	Description
`id`	`text`	Primary key
`value`	`text`	The label, unique
`external_id`	`text`, nullable	Id in an external system
`metadata`	`json`, nullable	Custom key-value data

Relations: products.

ProductType

A single classification per product. Table product_type, id prefix ptyp.

Field	Type	Description
`id`	`text`	Primary key
`value`	`text`	The type name, unique
`external_id`	`text`, nullable	Id in an external system
`metadata`	`json`, nullable	Custom key-value data

Relations: products.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Product

ProductVariant

ProductOption

ProductOptionValue

ProductImage

ProductCategory

ProductCollection

ProductTag

ProductType

​Product

​ProductVariant

​ProductOption

​ProductOptionValue

​ProductImage

​ProductCategory

​ProductCollection

​ProductTag

​ProductType

Product

ProductVariant

ProductOption

ProductOptionValue

ProductImage

ProductCategory

ProductCollection

ProductTag

ProductType