The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
title: "Catalog module links"
sidebarTitle: "Links"
description: "Every Mercur link on Product module models: both sides, cardinality, source file, and how to query it."
---
Mercur connects Medusa's Product module to its own modules through module links defined in `packages/core/src/links`. Read across a link with `query.graph` and the link's alias. Read-only links have no pivot table: they resolve from a foreign key column on one side, and you change them by updating that column.
Resolve `query` from the container before you run the examples:
```ts
import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
const query = container.resolve(ContainerRegistrationKeys.QUERY)
```
## Product and Seller
The store allowlist. A product with no rows is open to every store.
- **Sides**: `Product` (many) and `Seller` (many)
- **Storage**: pivot table `product_seller` with `product_id` and `seller_id`
- **Alias on product**: `sellers`
- **File**: `product-seller-link.ts`
```ts
const { data } = await query.graph({
entity: "product",
fields: ["id", "sellers.id", "sellers.name"],
filters: { id: "prod_01JD8Q1234567" },
})
```
Write it with `linkSellersToProductWorkflow` or the `seller_ids` input of `createProductsWorkflow`.
## ProductCategory and Seller
Links stores to categories. No shipped route filters products by it.
- **Sides**: `ProductCategory` (many) and `Seller` (many)
- **Storage**: pivot table generated by Medusa
- **Alias on category**: `sellers`
- **File**: `category-seller-link.ts`
```ts
const { data } = await query.graph({
entity: "product_category",
fields: ["id", "sellers.id"],
filters: { id: "pcat_01JD8Q1234567" },
})
```
Write it with `linkSellersToProductCategoryWorkflow`.
## Offer and Product
Each offer points at the master product it sells.
- **Sides**: `Offer` (one) to `Product` (one)
- **Storage**: read-only, through `offer.product_id`
- **Alias on offer**: `product`
- **File**: `offer-product-link.ts`
```ts
const { data } = await query.graph({
entity: "offer",
fields: ["id", "product.id", "product.title"],
filters: { product_id: "prod_01JD8Q1234567" },
})
```
To list a product's offers, query `offer` filtered by `product_id`, as above.
## Offer and ProductVariant
Each offer sells exactly one variant.
- **Sides**: `Offer` (one) to `ProductVariant` (one)
- **Storage**: read-only, through `offer.variant_id`
- **Alias on offer**: `product_variant`
- **File**: `offer-variant-link.ts`
```ts
const { data } = await query.graph({
entity: "offer",
fields: ["id", "product_variant.title", "product_variant.sku"],
filters: { variant_id: "variant_01JD8Q1234567" },
})
```
## Product and ProductChange
The audit and edit history of a product, including every `PRODUCT_ADD` and `STATUS_CHANGE` record.
- **Sides**: `Product` (one) to `ProductChange` (many)
- **Storage**: read-only, through `product_change.product_id`
- **Alias on product**: `changes`
- **File**: `product-change-link.ts`
```ts
const { data } = await query.graph({
entity: "product",
fields: ["id", "changes.status", "changes.created_by"],
filters: { id: "prod_01JD8Q1234567" },
})
```
## Product and ProductAttributeValue
The attribute values attached to a product.
- **Sides**: `Product` (many) and `ProductAttributeValue` (many)
- **Storage**: pivot table `product_attribute_value_link`
- **Alias on product**: `product_attribute_values`
- **File**: `product-attribute-value-pivot-link.ts`
```ts
const { data } = await query.graph({
entity: "product",
fields: [
"product_attribute_values.name",
"product_attribute_values.attribute.handle",
],
filters: { id: "prod_01JD8Q1234567" },
})
```
## Product and scoped ProductAttribute
Attributes created inline for one product.
- **Sides**: `Product` (one) to `ProductAttribute` (many)
- **Storage**: read-only, through `product_attribute.product_id`
- **Alias on product**: `scoped_attributes`
- **File**: `product-attribute-product-link.ts`
```ts
const { data } = await query.graph({
entity: "product",
fields: ["scoped_attributes.name", "scoped_attributes.values.name"],
filters: { id: "prod_01JD8Q1234567" },
})
```
## ProductAttribute and ProductCategory
Assigns attributes to categories.
- **Sides**: `ProductAttribute` (many) and `ProductCategory` (many)
- **Storage**: pivot table `product_category_attribute`
- **Alias on attribute**: `categories`
- **File**: `product-attribute-category-link.ts`
```ts
const { data } = await query.graph({
entity: "product_attribute",
fields: ["id", "categories.id", "categories.name"],
})
```
## Attribute option mirrors
A variant-axis attribute mirrors a native option, and each of its values mirrors an option value. Both links are one-to-one and read-only:
- **`ProductAttribute` to `ProductOption`**: through `product_attribute.product_option_id`, in `product-attribute-option-mirror-link.ts`
- **`ProductAttributeValue` to `ProductOptionValue`**: through `product_attribute_value.product_option_value_id`, in `product-attribute-value-option-value-mirror-link.ts`
Read the ids from the attribute side:
```ts
const { data } = await query.graph({
entity: "product_attribute",
fields: ["id", "product_option_id", "values.product_option_value_id"],
filters: { is_variant_axis: true },
})
```
## Product and Review
Customer reviews of a product.
- **Sides**: `Product` (one) to `Review` (many)
- **Storage**: pivot table generated by Medusa
- **Alias on product**: `reviews`
- **File**: `product-review.ts`
```ts
const { data } = await query.graph({
entity: "product",
fields: ["id", "reviews.id"],
filters: { id: "prod_01JD8Q1234567" },
})
```
## ProductCategory and ProductCollection images
Categories and collections own gallery and icon images from Mercur's media module.
- **Sides**: `ProductCategory` (one) to `MediaImage` (many), and `ProductCollection` (one) to `MediaImage` (many)
- **Alias**: `media_images` on both
- **Files**: `media-product-category-link.ts` and `media-product-collection-link.ts`
```ts
const { data } = await query.graph({
entity: "product_category",
fields: ["id", "media_images.url", "media_images.is_thumbnail"],
})
```
<Warning>
Don't define a link with the alias `images` on a category or collection. Both models live in the Product module, and that alias shadows `Product.images`, which breaks every product query.
</Warning>