Skip to main content
Use Mercur to keep one product catalog for the whole marketplace and control which stores can sell each product. The catalog is Medusa’s Product module (Modules.PRODUCT) with a marketplace layer on top. Products, variants, categories, collections, tags, and types are native Medusa models. Mercur adds the product_seller allowlist, a review flow over the product status, an audit record for every submission, and its own product workflows. No store owns a product: a store sells a master product through an offer that carries its own SKU, price, and stock. A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted. A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted.
There’s no Mercur catalog module. Resolve the service with Modules.PRODUCT from @medusajs/framework/utils, and run Mercur’s product workflows from @mercurjs/core/workflows. Mercur’s createProductsWorkflow has the same name as Medusa’s, so check the import path.

​
Key features

The catalog layer covers how products enter the marketplace and who can sell them:
  • Shared master products: one Product record per item, sold by any number of stores through offers
  • Store allowlist: the product_seller link restricts a product to the stores on it; a product with no rows is open to every store
  • Review flow: vendor submissions start as proposed and an operator publishes or rejects them
  • Submission audit: every create and review step writes a confirmed ProductChange record with the actor who did it
  • Attribute-driven variants: products take Mercur attributes on create, and variant-axis attributes become the options variants bind to
  • Native structure: variants, categories, collections, tags, and types come straight from Medusa’s Product module

​
How it works

A product moves through the catalog in a fixed order:
  1. A store or an operator runs createProductsWorkflow. Vendor submissions default to proposed.
  2. The workflow records a PRODUCT_ADD change with the creator as created_by, and links any seller_ids to the product.
  3. An operator runs confirmProductsWorkflow, rejectProductWorkflow, or requestProductChangeWorkflow on the proposed product.
  4. Once published, the product shows in the Store API and to every store its allowlist permits.
  5. Each store that sells it creates an offer against one of its variants.

​
Get started

Learn how master products, the allowlist, and statuses fit together.

Master products

Why products belong to the catalog and how Mercur records who submitted them.

The store allowlist

How the product_seller link decides which stores see and sell a product.

Status lifecycle

The four statuses and the workflow behind each transition.

Variants & categories

The Medusa models that structure the catalog, and where Mercur extends them.

​
Examples

Build against the catalog in your own server code.

Create a master product

Run createProductsWorkflow with attributes, variants, and an allowlist.

Allowlist stores

Restrict a product to chosen stores, or open it to all of them again.

Publish or reject

Review a proposed product from a route or a subscriber.

​
Resources

The data models, links, workflows, service methods, and events behind the catalog.

Data models

Product, ProductVariant, ProductCategory, and the other Product module models.

Links

How products and categories link to stores, offers, attributes, changes, and media.

Workflows

Mercur’s create, review, allowlist, and category workflows with their hooks.

Service

Medusa’s Product module service, resolved with Modules.PRODUCT.

Events

The events Mercur emits when products are created and reviewed.