Medusa v2 Catalog Management
Before writing code
Fetch live docs:
- Web-search
site:docs.medusajs.com product module for product data model and service methods
- Web-search
site:docs.medusajs.com product variant option for variant/option relationships
- Web-search
site:docs.medusajs.com collection category for collection and category APIs
- Fetch
https://docs.medusajs.com/resources/references/product and review the IProductModuleService interface
- Web-search
medusajs v2 product workflow 2026 for latest product-related workflow steps
- Web-search
site:docs.medusajs.com admin product api route for Admin API product endpoints
Product Model
Hierarchy
| Entity |
Relationship |
Key Fields |
| Product |
Root |
title, subtitle, description, handle, status |
| Options |
Product → many |
Size, Color, Material (with OptionValues) |
| Variants |
Product → many |
sku, barcode, ean, upc, hs_code |
| Prices |
Variant → many (link) |
Via Pricing Module link |
| Inventory |
Variant → one (link) |
Via Inventory Module link |
| Images |
Product → many |
url, rank |
| Tags |
Product ↔ many |
many-to-many labels |
| Categories |
Product ↔ many |
Nested tree (parent_category_id) |
| Collections |
Product ↔ many |
Curated groupings |
| Metadata |
On all entities |
JSONB key-value store |
Product Status
| Status |
Meaning |
draft |
Not visible to customers |
proposed |
Submitted for review |
published |
Visible on storefront |
rejected |
Review rejected |
Module Architecture
Medusa v2 uses a modular architecture where the Product Module is decoupled from pricing, inventory, and other concerns through Module Links.
Product Module ──link──> Pricing Module
Product Module ──link──> Inventory Module
Product Module ──link──> Sales Channel Module
Fetch live docs for exact link definitions and how to query across linked modules using remoteQuery.
Variants and Options
Relationship Model
| Entity |
Cardinality |
Description |
| Product -> Option |
one-to-many |
Each product defines its own options |
| Option -> OptionValue |
one-to-many |
Each option has enumerated values |
| Variant -> OptionValue |
many-to-many |
Each variant selects one value per option |
| Variant -> Price |
one-to-many |
Via Pricing Module link |
| Variant -> InventoryItem |
one-to-one |
Via Inventory Module link |
Key Service Methods
| Operation |
Method |
Notes |
| Create product |
productModuleService.createProducts() |
Accepts variants, options inline |
| Update product |
productModuleService.updateProducts() |
Partial updates supported |
| Delete product |
productModuleService.deleteProducts() |
Cascades to variants |
| List products |
productModuleService.listProducts() |
Supports filters, pagination |
| Retrieve product |
productModuleService.retrieveProduct() |
By ID with relations |
| Create variants |
productModuleService.createProductVariants() |
Link option values |
| Update variants |
productModuleService.updateProductVariants() |
Partial update |
Fetch live docs for the exact method signatures and filter/select/relations options available on each service method.
Minimal Workflow Pattern
// Skeleton: create product with variants
// Fetch live docs for createProductsWorkflow input shape
import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
const { result } = await createProductsWorkflow(container)
.run({ input: { products: [/* ... */] } })
// Fetch live docs for CreateProductsWorkflowInput
Collections
Logical groupings of products:
- Each collection has a
title, handle, and optional metadata
- Products can belong to multiple collections
- Managed via
productModuleService.createProductCollections()
- Useful for seasonal promotions, curated sets, and storefront navigation
Categories
Hierarchical classification with nesting:
| Field |
Description |
name |
Display name |
handle |
URL-friendly slug |
parent_category_id |
Reference to parent (null for root) |
rank |
Sort order among siblings |
is_active |
Visibility flag |
is_internal |
Hidden from storefront |
Categories form a tree structure — unlimited depth. Use category_children relation to traverse.
Fetch live docs for category service methods and nested tree query patterns.
Tags
Simple labels for filtering and organization:
- Stored as separate entities with a
value field
- Many-to-many relationship with products
- Queryable via
listProductTags()
- Use for lightweight cross-cutting classification (e.g., "new-arrival", "sale")
Product Metadata
JSONB key-value store on every product entity:
- Available on
Product, ProductVariant, ProductOption, and ProductCollection
- Schema-free — store arbitrary JSON values
- Queryable via filters:
metadata: { key: value }
- Use for custom attributes that don't warrant a dedicated field
Admin API Routes
| Route Pattern |
Method |
Purpose |
/admin/products |
GET |
List products with filters |
/admin/products |
POST |
Create product |
/admin/products/:id |
GET |
Retrieve single product |
/admin/products/:id |
POST |
Update product |
/admin/products/:id |
DELETE |
Delete product |
/admin/collections |
GET/POST |
Manage collections |
/admin/categories |
GET/POST |
Manage categories |
Fetch live docs for query parameters, request body shapes, and pagination patterns on each route.
Store API Routes
| Route Pattern |
Method |
Purpose |
/store/products |
GET |
List published products |
/store/products/:id |
GET |
Retrieve single product |
/store/collections |
GET |
List collections |
/store/categories |
GET |
List active categories |
Store routes respect sales channel and publishable API key scoping.
Best Practices
Data Modeling
- Use Options + Variants for product variations — do not duplicate products
- Leverage categories for hierarchical navigation and collections for curated groupings
- Store custom attributes in
metadata rather than creating custom modules for simple data
Performance
- Use
select and relations parameters to fetch only needed fields
- Use
remoteQuery for cross-module queries (product + pricing + inventory)
- Paginate large catalogs — never fetch all products without
limit and offset
Workflows
- Use
createProductsWorkflow and updateProductsWorkflow for transactional operations
- Workflows handle cross-module orchestration (linking prices, inventory) automatically
- Custom product logic should extend workflows via hooks, not bypass them
Module Isolation
- Never import Product Module internals directly — use the service interface
- Cross-module data access must go through links and
remoteQuery
- Respect module boundaries when building custom features
Fetch the Medusa v2 product module documentation and workflow references for exact service method signatures, workflow inputs, and remote query patterns before implementing.
1---2name: medusa-catalog3description: Manage the Medusa v2 catalog — products, variants, options, collections, categories, tags, and product metadata. Use when working with Medusa product data.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-catalog7---89# Medusa v2 Catalog Management1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.medusajs.com product module` for product data model and service methods152. Web-search `site:docs.medusajs.com product variant option` for variant/option relationships163. Web-search `site:docs.medusajs.com collection category` for collection and category APIs174. Fetch `https://docs.medusajs.com/resources/references/product` and review the `IProductModuleService` interface185. Web-search `medusajs v2 product workflow 2026` for latest product-related workflow steps196. Web-search `site:docs.medusajs.com admin product api route` for Admin API product endpoints2021## Product Model2223### Hierarchy2425| Entity | Relationship | Key Fields |26|--------|-------------|------------|27| **Product** | Root | title, subtitle, description, handle, status |28| **Options** | Product → many | Size, Color, Material (with OptionValues) |29| **Variants** | Product → many | sku, barcode, ean, upc, hs_code |30| **Prices** | Variant → many (link) | Via Pricing Module link |31| **Inventory** | Variant → one (link) | Via Inventory Module link |32| **Images** | Product → many | url, rank |33| **Tags** | Product ↔ many | many-to-many labels |34| **Categories** | Product ↔ many | Nested tree (parent_category_id) |35| **Collections** | Product ↔ many | Curated groupings |36| **Metadata** | On all entities | JSONB key-value store |3738### Product Status3940| Status | Meaning |41|--------|---------|42| `draft` | Not visible to customers |43| `proposed` | Submitted for review |44| `published` | Visible on storefront |45| `rejected` | Review rejected |4647### Module Architecture4849Medusa v2 uses a **modular architecture** where the Product Module is decoupled from pricing, inventory, and other concerns through **Module Links**.5051```52Product Module ──link──> Pricing Module53Product Module ──link──> Inventory Module54Product Module ──link──> Sales Channel Module55```5657> **Fetch live docs** for exact link definitions and how to query across linked modules using `remoteQuery`.5859## Variants and Options6061### Relationship Model6263| Entity | Cardinality | Description |64|--------|-------------|-------------|65| Product -> Option | one-to-many | Each product defines its own options |66| Option -> OptionValue | one-to-many | Each option has enumerated values |67| Variant -> OptionValue | many-to-many | Each variant selects one value per option |68| Variant -> Price | one-to-many | Via Pricing Module link |69| Variant -> InventoryItem | one-to-one | Via Inventory Module link |7071### Key Service Methods7273| Operation | Method | Notes |74|-----------|--------|-------|75| Create product | `productModuleService.createProducts()` | Accepts variants, options inline |76| Update product | `productModuleService.updateProducts()` | Partial updates supported |77| Delete product | `productModuleService.deleteProducts()` | Cascades to variants |78| List products | `productModuleService.listProducts()` | Supports filters, pagination |79| Retrieve product | `productModuleService.retrieveProduct()` | By ID with relations |80| Create variants | `productModuleService.createProductVariants()` | Link option values |81| Update variants | `productModuleService.updateProductVariants()` | Partial update |8283> **Fetch live docs** for the exact method signatures and filter/select/relations options available on each service method.8485### Minimal Workflow Pattern8687```ts88// Skeleton: create product with variants89// Fetch live docs for createProductsWorkflow input shape90import { createProductsWorkflow } from "@medusajs/medusa/core-flows"9192const { result } = await createProductsWorkflow(container)93 .run({ input: { products: [/* ... */] } })94// Fetch live docs for CreateProductsWorkflowInput95```9697## Collections9899Logical groupings of products:100- Each collection has a `title`, `handle`, and optional `metadata`101- Products can belong to multiple collections102- Managed via `productModuleService.createProductCollections()`103- Useful for seasonal promotions, curated sets, and storefront navigation104105## Categories106107Hierarchical classification with nesting:108109| Field | Description |110|-------|-------------|111| `name` | Display name |112| `handle` | URL-friendly slug |113| `parent_category_id` | Reference to parent (null for root) |114| `rank` | Sort order among siblings |115| `is_active` | Visibility flag |116| `is_internal` | Hidden from storefront |117118Categories form a **tree structure** — unlimited depth. Use `category_children` relation to traverse.119120> **Fetch live docs** for category service methods and nested tree query patterns.121122## Tags123124Simple labels for filtering and organization:125- Stored as separate entities with a `value` field126- Many-to-many relationship with products127- Queryable via `listProductTags()`128- Use for lightweight cross-cutting classification (e.g., "new-arrival", "sale")129130## Product Metadata131132JSONB key-value store on every product entity:133- Available on `Product`, `ProductVariant`, `ProductOption`, and `ProductCollection`134- Schema-free — store arbitrary JSON values135- Queryable via filters: `metadata: { key: value }`136- Use for custom attributes that don't warrant a dedicated field137138## Admin API Routes139140| Route Pattern | Method | Purpose |141|---------------|--------|---------|142| `/admin/products` | GET | List products with filters |143| `/admin/products` | POST | Create product |144| `/admin/products/:id` | GET | Retrieve single product |145| `/admin/products/:id` | POST | Update product |146| `/admin/products/:id` | DELETE | Delete product |147| `/admin/collections` | GET/POST | Manage collections |148| `/admin/categories` | GET/POST | Manage categories |149150> **Fetch live docs** for query parameters, request body shapes, and pagination patterns on each route.151152## Store API Routes153154| Route Pattern | Method | Purpose |155|---------------|--------|---------|156| `/store/products` | GET | List published products |157| `/store/products/:id` | GET | Retrieve single product |158| `/store/collections` | GET | List collections |159| `/store/categories` | GET | List active categories |160161Store routes respect **sales channel** and **publishable API key** scoping.162163## Best Practices164165### Data Modeling166- Use **Options + Variants** for product variations — do not duplicate products167- Leverage **categories** for hierarchical navigation and **collections** for curated groupings168- Store custom attributes in `metadata` rather than creating custom modules for simple data169170### Performance171- Use `select` and `relations` parameters to fetch only needed fields172- Use `remoteQuery` for cross-module queries (product + pricing + inventory)173- Paginate large catalogs — never fetch all products without `limit` and `offset`174175### Workflows176- Use `createProductsWorkflow` and `updateProductsWorkflow` for transactional operations177- Workflows handle cross-module orchestration (linking prices, inventory) automatically178- Custom product logic should extend workflows via hooks, not bypass them179180### Module Isolation181- Never import Product Module internals directly — use the service interface182- Cross-module data access must go through links and `remoteQuery`183- Respect module boundaries when building custom features184185Fetch the Medusa v2 product module documentation and workflow references for exact service method signatures, workflow inputs, and remote query patterns before implementing.