Skip to main content
Use Mercur to put seller edits to the shared catalog through review, and to keep a durable history of every change to a product. Products in Mercur form one shared catalog that every seller sells against, so a seller can’t write to a product directly. Each edit becomes a ProductChange record that holds typed actions, one per changed field, variant, or attribute. The change waits as pending until an operator confirms or declines it, or its author cancels it. Confirmed changes, together with publish approvals, rejections, and revision requests, form the product’s audit trail. A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail. A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail.
The Product Edit module (MercurModules.PRODUCT_EDIT) governs changes to a product. It never makes a store the owner of one. Products live in Medusa’s Product module, and sellers sell them through offers.

​
How it works

A seller edit moves through the pipeline in five steps:
  1. A vendor route runs an edit workflow such as productEditUpdateProductWorkflow, which diffs the input against the product and stages a pending change with one action per difference.
  2. autoConfirmProductChangeWorkflow runs right after staging. With the product_request feature flag on, the default, the change stays pending.
  3. An operator confirms or declines the change, or the seller cancels it.
  4. On confirm, applyProductChangeActionsWorkflow writes the actions to the product through Medusa’s product workflows and marks each action applied.
  5. Product creation, publish approvals, rejections, and revision requests are recorded as changes that start out confirmed, so the trail is complete without a review.

​
Key features

The module covers the full path of an edit, from diff to audit record:
  • Field-level diffs: the edit workflows stage only the fields, variants, and attributes that differ from the current product
  • Typed actions: each change holds ProductChangeAction rows such as UPDATE, VARIANT_ADD, ATTRIBUTE_UPDATE, or PRODUCT_DELETE
  • Review queue: a change moves from pending to confirmed, declined, or canceled, each through its own workflow and event
  • Deferred writes: actions touch the product only when the change is confirmed
  • Auto-confirm: turn off the product_request flag, or pass auto_confirm, to apply a change in the same run
  • Revision requests: an operator sends a proposed product back to its seller with a recorded CHANGE_REQUESTED action
  • One open change per author: the edit workflows reject a new change while the same author has one pending on the product

​
Get started

Learn how changes, actions, and statuses fit together.

The change pipeline

How an edit becomes a ProductChange and how the audit trail builds up.

Change actions

The action types, the details each one carries, and how they apply.

Status & auto-confirm

The status lifecycle, revision requests, and when a change skips review.

​
Examples

Build against the change pipeline in your own server code.

Edit a product

Stage field, variant, and attribute changes from a custom route.

Confirm or decline

Resolve a pending change and react to the result.

Request a revision

Send a proposed product back to its seller with a message.

​
Resources

The data models, links, workflows, service methods, and events behind product edits.

Data models

The ProductChange and ProductChangeAction models and their enums.

Links

The read-only product.changes link to Medusa’s Product module.

Workflows

Staging, resolution, apply, edit, and audit workflows with their hooks.

Service

Generated methods on the Product Edit module service.

Events

The product-change.* events and the revision request event.