Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

3.9 KB
Raw Blame
---
title: "Product module service"
sidebarTitle: "Service"
description: "Resolve Medusa's Product module service with Modules.PRODUCT and call its methods for catalog records."
---

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`:

```ts
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.

<Warning>
  The service writes rows directly. It doesn't link stores, record `ProductChange` entries, or emit Mercur's `product.*` events. Use the [catalog workflows](/platform/catalog/reference/workflows) for creates and reviews, and `query.graph` to read linked data such as `sellers`.
</Warning>

## 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.