Medusa v2 Catalog Management

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com product module for product data model and service methods
2. Web-search site:docs.medusajs.com product variant option for variant/option relationships
3. Web-search site:docs.medusajs.com collection category for collection and category APIs
4. Fetch https://docs.medusajs.com/resources/references/product and review the IProductModuleService interface
5. Web-search medusajs v2 product workflow 2026 for latest product-related workflow steps
6. Web-search site:docs.medusajs.com admin product api route for Admin API product endpoints

Product Model

Hierarchy

Product Status

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

Key Service Methods

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:

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

Fetch live docs for query parameters, request body shapes, and pagination patterns on each route.

Store API Routes

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.