Product module service

The catalog uses Medusa’s Product module service. Mercur adds no catalog service of its own. Resolve it with Modules.PRODUCT to read and write products, variants, options, categories, collections, tags, and types from a subscriber, a scheduled job, or a custom step.

Resolve the service

The service key comes from @medusajs/framework/utils, not MercurModules:

import { Modules } from "@medusajs/framework/utils"

const productService = container.resolve(Modules.PRODUCT)

const [products, count] = await productService.listAndCountProducts(
  { status: "published" },
  { take: 20, select: ["id", "title"] }
)

listAndCountProducts returns a page of products and the total count.

The service writes rows directly. It doesn’t link stores, record ProductChange entries, or emit Mercur’s product.* events. Use the catalog workflows for creates and reviews, and query.graph to read linked data such as sellers.

Product methods

These methods act on Product:

Method	Signature
`retrieveProduct`	`(productId: string, config?) => Promise<ProductDTO>`
`listProducts`	`(filters?, config?) => Promise<ProductDTO[]>`
`listAndCountProducts`	`(filters?, config?) => Promise<[ProductDTO[], number]>`
`createProducts`	`(data: CreateProductDTO \| CreateProductDTO[]) => Promise<ProductDTO \| ProductDTO[]>`
`upsertProducts`	`(data: UpsertProductDTO \| UpsertProductDTO[]) => Promise<ProductDTO \| ProductDTO[]>`
`updateProducts`	`(id: string, data) => Promise<ProductDTO>` or `(selector, data) => Promise<ProductDTO[]>`
`deleteProducts`	`(productIds: string[]) => Promise<void>`
`softDeleteProducts`	`(productIds: string[], config?) => Promise<Record<string, string[]> \| void>`
`restoreProducts`	`(productIds: string[], config?) => Promise<Record<string, string[]> \| void>`

filters takes FilterableProductProps, such as id, status, handle, or q. config takes select, relations, skip, take, and order.

Methods for the other models

The same method set exists for each model in the module, named after it:

Model	Example methods
`ProductVariant`	`retrieveProductVariant`, `listProductVariants`, `createProductVariants`, `updateProductVariants`
`ProductOption`	`listProductOptions`, `createProductOptions`, `upsertProductOptions`, `deleteProductOptions`
`ProductOptionValue`	`listProductOptionValues`, `createProductOptionValues`, `updateProductOptionValues`
`ProductCategory`	`retrieveProductCategory`, `listProductCategories`, `createProductCategories`
`ProductCollection`	`retrieveProductCollection`, `listProductCollections`, `updateProductCollections`
`ProductTag`	`listProductTags`, `createProductTags`, `upsertProductTags`, `deleteProductTags`
`ProductType`	`listProductTypes`, `createProductTypes`, `upsertProductTypes`, `deleteProductTypes`

Option and image methods

The service also has methods that manage shared options and variant images:

Method	Does
`addProductOptionToProduct`	Attaches an existing option to a product, from `{ product_id, product_option_id }` or an array
`removeProductOptionFromProduct`	Detaches an option from a product
`updateProductOptionValuesOnProduct`	Changes which values of an option a product uses
`addImageToVariant`	Links a product image to a variant
`removeImageFromVariant`	Unlinks a product image from a variant

Mercur’s attribute workflows create and attach the options behind variant-axis attributes. Prefer those workflows over the option methods, so each attribute stays in sync with the option it mirrors.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Resolve the service

Product methods

Methods for the other models

Option and image methods

​Resolve the service

​Product methods

​Methods for the other models

​Option and image methods

Resolve the service

Product methods

Methods for the other models

Option and image methods