From medusa-commerce
Manage Medusa v2 catalog—products, variants, options, collections, categories, tags, and product metadata. Useful when working with Medusa product data.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin medusa-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Fetch live docs:
site:docs.medusajs.com product module for product data model and service methodssite:docs.medusajs.com product variant option for variant/option relationshipssite:docs.medusajs.com collection category for collection and category APIshttps://docs.medusajs.com/resources/references/product and review the IProductModuleService interfacemedusajs v2 product workflow 2026 for latest product-related workflow stepssite:docs.medusajs.com admin product api route for Admin API product endpoints| 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 |
| Status | Meaning |
|---|---|
draft | Not visible to customers |
proposed | Submitted for review |
published | Visible on storefront |
rejected | Review rejected |
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.
| 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 |
| 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.
// 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
Logical groupings of products:
title, handle, and optional metadataproductModuleService.createProductCollections()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.
Simple labels for filtering and organization:
value fieldlistProductTags()JSONB key-value store on every product entity:
Product, ProductVariant, ProductOption, and ProductCollectionmetadata: { key: value }| 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.
| 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.
metadata rather than creating custom modules for simple dataselect and relations parameters to fetch only needed fieldsremoteQuery for cross-module queries (product + pricing + inventory)limit and offsetcreateProductsWorkflow and updateProductsWorkflow for transactional operationsremoteQueryFetch the Medusa v2 product module documentation and workflow references for exact service method signatures, workflow inputs, and remote query patterns before implementing.