@mercurjs/docs 2.3.8-canary.3 → 2.3.9-canary.1

package/content/platform/catalog/reference/data-models.mdx

@@ -1,66 +1,177 @@
 ---
-title: "Data models"
+title: "Catalog data models"
 sidebarTitle: "Data models"
-description: "The Medusa Product models the catalog is built on, plus Mercur's marketplace layer."
+description: "Every field on the Medusa Product module models the shared catalog is built on, and the relations Mercur adds."
 ---
 
-The Catalog domain is owned by **Medusa's Product module**, with a marketplace
-layer added by Mercur. This reference lists the models at the Mercur-relevant
-level. It doesn't restate every Medusa product field. For the full module, see
-the [Medusa Product module](https://docs.medusajs.com/resources/commerce-modules/product).
+The catalog's data models belong to Medusa's Product module, version 2.22. Mercur adds no columns to them. It adds relations through [module links](/platform/catalog/reference/links), listed under each model. Every model also has `created_at`, `updated_at`, and `deleted_at` timestamps that Medusa manages.
 
 ## Product
 
-Table `product`, id prefix `prod`. The shared master product, not owned by any
-store. The marketplace-relevant fields:
+The shared master product. Table `product`, id prefix `prod`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `title` | text | Searchable |
-| `handle` | text | Unique |
-| `subtitle` / `description` | text | Nullable |
-| `status` | enum | `ProductStatus`: `draft` / `proposed` / `published` / `rejected`, default `draft` |
-| `thumbnail` | text | Nullable |
-| `metadata` | json | Nullable |
+| `id` | `text` | Primary key |
+| `title` | `text` | Display title, searchable and translatable |
+| `handle` | `text` | URL handle, unique among non-deleted products |
+| `subtitle` | `text`, nullable | Subtitle, searchable and translatable |
+| `description` | `text`, nullable | Description, searchable and translatable |
+| `is_giftcard` | `boolean` | Whether the product is a gift card. Default `false` |
+| `status` | `enum` | `draft`, `proposed`, `published`, or `rejected`. Default `draft` |
+| `thumbnail` | `text`, nullable | Thumbnail image URL |
+| `weight` | `float`, nullable | Weight |
+| `length` | `float`, nullable | Length |
+| `height` | `float`, nullable | Height |
+| `width` | `float`, nullable | Width |
+| `origin_country` | `text`, nullable | Country of origin |
+| `hs_code` | `text`, nullable | Harmonized System code |
+| `mid_code` | `text`, nullable | Manufacturer identification code |
+| `material` | `text`, nullable | Material, translatable |
+| `discountable` | `boolean` | Whether promotions can apply. Default `true` |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Native relations:
+
+- **`variants`**: `ProductVariant[]`, deleted with the product
+- **`options`**: `ProductOption[]` through the `ProductProductOption` pivot
+- **`images`**: `ProductImage[]`, deleted with the product
+- **`categories`**: `ProductCategory[]` through `product_category_product`
+- **`collection`**: `ProductCollection`, nullable
+- **`type`**: `ProductType`, nullable
+- **`tags`**: `ProductTag[]` through `product_tags`
+
+Mercur relations:
+
+- **`sellers`**: `Seller[]`, the store allowlist in `product_seller`
+- **`product_attribute_values`**: attribute values attached to the product
+- **`scoped_attributes`**: product-scoped attributes, read-only
+- **`changes`**: `ProductChange[]`, the audit and edit history, read-only
+- **`reviews`**: `Review[]`
 
-Relations used by the marketplace: `variants`, `options`, `categories`,
-`collection`, `tags`, `type`, `images` (native Medusa), plus Mercur's `sellers`
-(the allowlist), `offers`, `scoped_attributes`, and `changes` (audit history).
+## ProductVariant
 
-## product_seller
+One purchasable configuration of a product. Table `product_variant`, id prefix `variant`.
 
-The **allowlist**: a many-to-many link table between `Product` and `Seller`
-controlling which stores may sell a master product.
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `title` | `text` | Display title, searchable and translatable |
+| `sku` | `text`, nullable | Catalog SKU, unique among non-deleted variants |
+| `barcode` | `text`, nullable | Barcode, unique |
+| `ean` | `text`, nullable | EAN, unique |
+| `upc` | `text`, nullable | UPC, unique |
+| `allow_backorder` | `boolean` | Default `false` |
+| `manage_inventory` | `boolean` | Model default `true`; Mercur's create workflow sends `false` |
+| `hs_code` | `text`, nullable | Harmonized System code |
+| `origin_country` | `text`, nullable | Country of origin |
+| `mid_code` | `text`, nullable | Manufacturer identification code |
+| `material` | `text`, nullable | Material, translatable |
+| `weight` | `float`, nullable | Weight |
+| `length` | `float`, nullable | Length |
+| `height` | `float`, nullable | Height |
+| `width` | `float`, nullable | Width |
+| `thumbnail` | `text`, nullable | Variant thumbnail URL |
+| `variant_rank` | `number`, nullable | Sort order. Default `0` |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `product` (nullable), `options` (`ProductOptionValue[]` through `product_variant_option`), and `images` (`ProductImage[]`). Mercur links offers to variants through `offer.variant_id`. Each store's price and stock live on the [offer](/platform/offer/reference/data-models), not here.
+
+## ProductOption
+
+An axis that variants vary on. Table `product_option`, id prefix `opt`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `title` | `text` | Option name, such as `Size` |
+| `is_exclusive` | `boolean` | `true` when the option belongs to one product. Default `false` |
+| `metadata` | `json`, nullable | Custom key-value data |
 
-| Column | References |
-| --- | --- |
-| `product_id` | `product.id` |
-| `seller_id` | `seller.id` |
+Relations: `products` and `values` (`ProductOptionValue[]`). A variant-axis attribute mirrors one option through `product_attribute.product_option_id`.
 
-A store on this table can create an [offer](/platform/offer/overview) against the
-product; a store not on it cannot.
+## ProductOptionValue
 
-## ProductVariant
+One value of an option. Table `product_option_value`, id prefix `optval`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `value` | `text` | The value, such as `M` |
+| `rank` | `number`, nullable | Sort order |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `option` (nullable), `variants`, and `product_options`.
 
-Table `product_variant`, id prefix `variant`. A purchasable configuration of a
-master product, generated from its options and variant-axis attributes. Holds the
-SKU-level catalog structure. Offer-scoped price and inventory live on the offer,
-not here.
+## ProductImage
+
+A product image. Table `image`, id prefix `img`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `url` | `text` | Image URL |
+| `rank` | `number` | Sort order. Default `0` |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `product` and `variants`.
 
 ## ProductCategory
 
-Table `product_category`, id prefix `pcat`. Hierarchical, nestable
-classification. Participates in the marketplace layer through the
-`category_seller` allowlist and the `media_images` link.
+A node in the category tree. Table `product_category`, id prefix `pcat`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `name` | `text` | Display name, searchable and translatable |
+| `description` | `text` | Description. Default `""` |
+| `handle` | `text` | URL handle, unique |
+| `mpath` | `text` | Materialized path of ancestor ids |
+| `is_active` | `boolean` | Whether the category is live. Default `false` |
+| `is_internal` | `boolean` | Hidden from the storefront. Default `false` |
+| `rank` | `number` | Sort order among siblings. Default `0` |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `parent_category` (nullable), `category_children` (deleted with the parent), and `products`. Mercur adds `sellers`, `media_images`, and the product attribute link.
 
 ## ProductCollection
 
-Table `product_collection`, id prefix `pcol`. Flat, curated grouping of products,
-with a `media_images` link for collection artwork.
+A flat group of products. Table `product_collection`, id prefix `pcol`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `title` | `text` | Display title, searchable and translatable |
+| `handle` | `text` | URL handle, unique |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `products`. Mercur adds `media_images`.
+
+## ProductTag
+
+A free-form label. Table `product_tag`, id prefix `ptag`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `value` | `text` | The label, unique |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations: `products`.
+
+## ProductType
+
+A single classification per product. Table `product_type`, id prefix `ptyp`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `text` | Primary key |
+| `value` | `text` | The type name, unique |
+| `external_id` | `text`, nullable | Id in an external system |
+| `metadata` | `json`, nullable | Custom key-value data |
 
-<Note>
-  `ProductTag` and `ProductType` round out the native grouping models: free-form
-  labels and a single type classification per product, respectively. They carry
-  no Mercur-specific columns.
-</Note>
+Relations: `products`.

package/content/platform/catalog/reference/events.mdx

@@ -1,41 +1,57 @@
 ---
-title: "Event reference"
+title: "Catalog events"
 sidebarTitle: "Events"
-description: "Events emitted by the Catalog domain, for subscribers and side effects."
+description: "The events Mercur's product workflows emit, their payloads, and how to subscribe to them."
 ---
 
-The Catalog domain emits events as products are created and reviewed. Subscribe
-to them to run side effects instead of polling, such as sending notifications,
-syncing external systems, or reindexing search.
+Mercur's product workflows emit 4 events as products are created and reviewed. The names are exported as `ProductWorkflowEvents` from `@mercurjs/core/workflows`. Subscribe to them to notify stores, sync external systems, or reindex search.
 
-```ts title="src/subscribers/product-published.ts"
+## Product events
+
+Each event is emitted once per product. Payloads come from the `emitEventStep` calls in `packages/core/src/workflows/product/workflows`.
+
+| Event | Constant | Emitted when | Payload |
+| --- | --- | --- | --- |
+| `product.created` | `CREATED` | `createProductsWorkflow` creates a product | `{ id }` |
+| `product.published` | `PUBLISHED` | `confirmProductsWorkflow` publishes a product | `{ id, internal_note? }` |
+| `product.rejected` | `REJECTED` | `rejectProductWorkflow` rejects a product | `{ id, message? }` |
+| `product.change-requested` | `CHANGE_REQUESTED` | `requestProductChangeWorkflow` asks for a revision | `{ id, message?, actor_id? }` |
+
+<Warning>
+  Mercur's `createProductsWorkflow` runs Medusa's `createProductsWorkflow` as a step, which also emits `product.created` with `{ id }`. Expect 2 `product.created` events per product and make handlers idempotent.
+</Warning>
+
+## Subscribe to an event
+
+Write a subscriber that listens for one of the events. This one logs the rejection reason for each rejected product.
+
+```ts title="src/subscribers/product-rejected.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ProductWorkflowEvents } from "@mercurjs/core/workflows"
 
-export default async function productPublishedHandler({
+export default async function productRejected({
   event,
   container,
-}: SubscriberArgs<{ id: string }>) {
-  const productId = event.data.id
-  // ...reindex search, notify the seller, etc.
+}: SubscriberArgs<{ id: string; message?: string }>) {
+  const logger = container.resolve("logger")
+  const reason = event.data.message ?? "no reason given"
+
+  logger.info(`Product ${event.data.id} rejected: ${reason}`)
 }
 
 export const config: SubscriberConfig = {
-  event: "product.published",
+  event: ProductWorkflowEvents.REJECTED,
 }
 ```
 
-## Product events
+Medusa calls the handler once per rejected product with the payload above.
+
+## Events from Medusa
+
+Medusa's own product workflows emit their events alongside Mercur's. These matter for the catalog:
+
+- **`product.updated`**: from Medusa's `updateProductsWorkflow`, which `assignProductsToCategoryWorkflow` and the admin product update both run
+- **`product.deleted`**: from Medusa's `deleteProductsWorkflow`
+- **`product-variant.created`**: from `createProductVariantsWorkflow`, which Mercur's create workflow runs for `variants`
 
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product.created` | A master product is created | `{ id }` |
-| `product.published` | A proposed product is approved (`→ published`) | `{ id, internal_note? }` |
-| `product.rejected` | A proposed product is rejected | `{ id, message? }` |
-| `product.change-requested` | A revision is requested on a proposed product | `{ id, message?, actor_id? }` |
-
-<Note>
-  These are the marketplace lifecycle events emitted by Mercur's product
-  workflows. Medusa's Product module also emits its own native events (e.g.
-  `product.updated`, `product-variant.created`) for lower-level changes. See the
-  [Medusa events reference](https://docs.medusajs.com/resources/events-reference).
-</Note>
+See the [Medusa events reference](https://docs.medusajs.com/resources/references/events) for the full list. Edits that stores submit through the product edit pipeline emit `product-change.*` events, listed in the [product edit events](/platform/product-edit/reference/events).

package/content/platform/catalog/reference/links.mdx

@@ -1,44 +1,212 @@
 ---
-title: "Links to other modules"
+title: "Catalog module links"
 sidebarTitle: "Links"
-description: "How the catalog links to sellers, offers, attributes, and media."
+description: "Every Mercur link on Product module models: both sides, cardinality, source file, and how to query it."
 ---
 
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The Catalog (Medusa's `Product` module) is wired into the
-marketplace layer with a set of links defined in Mercur core. Once a link is
-defined, you retrieve related records with `query.graph` using the link alias.
+Mercur connects Medusa's Product module to its own modules through module links defined in `packages/core/src/links`. Read across a link with `query.graph` and the link's alias. Read-only links have no pivot table: they resolve from a foreign key column on one side, and you change them by updating that column.
+
+Resolve `query` from the container before you run the examples:
+
+```ts
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+const query = container.resolve(ContainerRegistrationKeys.QUERY)
+```
+
+## Product and Seller
+
+The store allowlist. A product with no rows is open to every store.
+
+- **Sides**: `Product` (many) and `Seller` (many)
+- **Storage**: pivot table `product_seller` with `product_id` and `seller_id`
+- **Alias on product**: `sellers`
+- **File**: `product-seller-link.ts`
+
+```ts
+const { data } = await query.graph({
+  entity: "product",
+  fields: ["id", "sellers.id", "sellers.name"],
+  filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+Write it with `linkSellersToProductWorkflow` or the `seller_ids` input of `createProductsWorkflow`.
+
+## ProductCategory and Seller
+
+Links stores to categories. No shipped route filters products by it.
+
+- **Sides**: `ProductCategory` (many) and `Seller` (many)
+- **Storage**: pivot table generated by Medusa
+- **Alias on category**: `sellers`
+- **File**: `category-seller-link.ts`
+
+```ts
+const { data } = await query.graph({
+  entity: "product_category",
+  fields: ["id", "sellers.id"],
+  filters: { id: "pcat_01JD8Q1234567" },
+})
+```
+
+Write it with `linkSellersToProductCategoryWorkflow`.
+
+## Offer and Product
+
+Each offer points at the master product it sells.
+
+- **Sides**: `Offer` (one) to `Product` (one)
+- **Storage**: read-only, through `offer.product_id`
+- **Alias on offer**: `product`
+- **File**: `offer-product-link.ts`
+
+```ts
+const { data } = await query.graph({
+  entity: "offer",
+  fields: ["id", "product.id", "product.title"],
+  filters: { product_id: "prod_01JD8Q1234567" },
+})
+```
+
+To list a product's offers, query `offer` filtered by `product_id`, as above.
+
+## Offer and ProductVariant
+
+Each offer sells exactly one variant.
+
+- **Sides**: `Offer` (one) to `ProductVariant` (one)
+- **Storage**: read-only, through `offer.variant_id`
+- **Alias on offer**: `product_variant`
+- **File**: `offer-variant-link.ts`
+
+```ts
+const { data } = await query.graph({
+  entity: "offer",
+  fields: ["id", "product_variant.title", "product_variant.sku"],
+  filters: { variant_id: "variant_01JD8Q1234567" },
+})
+```
+
+## Product and ProductChange
+
+The audit and edit history of a product, including every `PRODUCT_ADD` and `STATUS_CHANGE` record.
+
+- **Sides**: `Product` (one) to `ProductChange` (many)
+- **Storage**: read-only, through `product_change.product_id`
+- **Alias on product**: `changes`
+- **File**: `product-change-link.ts`
 
 ```ts
-const { data: products } = await query.graph({
+const { data } = await query.graph({
   entity: "product",
-  fields: ["id", "title", "sellers.*", "offers.*", "changes.*"],
+  fields: ["id", "changes.status", "changes.created_by"],
+  filters: { id: "prod_01JD8Q1234567" },
 })
 ```
 
-## Marketplace
+## Product and ProductAttributeValue
 
-| Linked module | Relationship |
-| --- | --- |
-| **Seller** | Many-to-many allowlist (`product_seller`) that controls which stores may sell a master product. Categories carry the same via `category_seller`. |
-| **Offer** | A product has many offers (`offer.product_id`, read-only). Offers are how a store sells against the master product. |
-| **Product change** | A product has many change records (`product.changes`, read-only): the immutable submission and review audit trail. |
+The attribute values attached to a product.
 
-## Attributes
+- **Sides**: `Product` (many) and `ProductAttributeValue` (many)
+- **Storage**: pivot table `product_attribute_value_link`
+- **Alias on product**: `product_attribute_values`
+- **File**: `product-attribute-value-pivot-link.ts`
 
-| Linked module | Relationship |
-| --- | --- |
-| **Product attribute** | Product-scoped attributes resolve under `product.scoped_attributes` (read-only). Categories link attributes through `product_category_attribute`. |
+```ts
+const { data } = await query.graph({
+  entity: "product",
+  fields: [
+    "product_attribute_values.name",
+    "product_attribute_values.attribute.handle",
+  ],
+  filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## Product and scoped ProductAttribute
+
+Attributes created inline for one product.
+
+- **Sides**: `Product` (one) to `ProductAttribute` (many)
+- **Storage**: read-only, through `product_attribute.product_id`
+- **Alias on product**: `scoped_attributes`
+- **File**: `product-attribute-product-link.ts`
+
+```ts
+const { data } = await query.graph({
+  entity: "product",
+  fields: ["scoped_attributes.name", "scoped_attributes.values.name"],
+  filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## ProductAttribute and ProductCategory
+
+Assigns attributes to categories.
+
+- **Sides**: `ProductAttribute` (many) and `ProductCategory` (many)
+- **Storage**: pivot table `product_category_attribute`
+- **Alias on attribute**: `categories`
+- **File**: `product-attribute-category-link.ts`
+
+```ts
+const { data } = await query.graph({
+  entity: "product_attribute",
+  fields: ["id", "categories.id", "categories.name"],
+})
+```
+
+## Attribute option mirrors
 
-## Media
+A variant-axis attribute mirrors a native option, and each of its values mirrors an option value. Both links are one-to-one and read-only:
 
-| Linked module | Relationship |
-| --- | --- |
-| **Media** | Categories and collections link their artwork through the `media_images` alias (a `MediaImage` list). |
+- **`ProductAttribute` to `ProductOption`**: through `product_attribute.product_option_id`, in `product-attribute-option-mirror-link.ts`
+- **`ProductAttributeValue` to `ProductOptionValue`**: through `product_attribute_value.product_option_value_id`, in `product-attribute-value-option-value-mirror-link.ts`
+
+Read the ids from the attribute side:
+
+```ts
+const { data } = await query.graph({
+  entity: "product_attribute",
+  fields: ["id", "product_option_id", "values.product_option_value_id"],
+  filters: { is_variant_axis: true },
+})
+```
+
+## Product and Review
+
+Customer reviews of a product.
+
+- **Sides**: `Product` (one) to `Review` (many)
+- **Storage**: pivot table generated by Medusa
+- **Alias on product**: `reviews`
+- **File**: `product-review.ts`
+
+```ts
+const { data } = await query.graph({
+  entity: "product",
+  fields: ["id", "reviews.id"],
+  filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## ProductCategory and ProductCollection images
+
+Categories and collections own gallery and icon images from Mercur's media module.
+
+- **Sides**: `ProductCategory` (one) to `MediaImage` (many), and `ProductCollection` (one) to `MediaImage` (many)
+- **Alias**: `media_images` on both
+- **Files**: `media-product-category-link.ts` and `media-product-collection-link.ts`
+
+```ts
+const { data } = await query.graph({
+  entity: "product_category",
+  fields: ["id", "media_images.url", "media_images.is_thumbnail"],
+})
+```
 
-<Note>
-  Read-only links (Offer, Product change, scoped attributes) are resolved from
-  the field on the owning record and can't be written through the link itself.
-  The `media_images` alias is deliberately **not** the bare `images` alias. That
-  would shadow the native `Product.images` relation and break product queries.
-</Note>
+<Warning>
+  Don't define a link with the alias `images` on a category or collection. Both models live in the Product module, and that alias shadows `Product.images`, which breaks every product query.
+</Warning>

package/content/platform/catalog/reference/service.mdx

@@ -1,52 +1,74 @@
 ---
-title: "Service reference"
+title: "Product module service"
 sidebarTitle: "Service"
-description: "Medusa's Product module service: methods for working with records directly."
+description: "Resolve Medusa's Product module service with Modules.PRODUCT and call its methods for catalog records."
 ---
 
-The catalog is backed by **Medusa's Product module**, not a Mercur-specific one.
-Resolve its service from the container with the `Modules.PRODUCT` key to read and
-write products, variants, categories, and collections directly, without going
-through a workflow. Use it inside custom services, subscribers, or scheduled jobs.
+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 productModuleService = container.resolve(Modules.PRODUCT)
+const productService = container.resolve(Modules.PRODUCT)
 
-const [products, count] = await productModuleService.listAndCountProducts({
-  status: "published",
-})
+const [products, count] = await productService.listAndCountProducts(
+  { status: "published" },
+  { take: 20, select: ["id", "title"] }
+)
 ```
 
-<Note>
-  Because this is Medusa's own module, the service key is `Modules.PRODUCT` from
-  `@medusajs/framework/utils`, **not** a `MercurModules` key. Mercur adds its
-  marketplace behavior (allowlist, review lifecycle, audit trail) as
-  [workflows](/platform/catalog/reference/workflows) layered on top of this
-  service.
-</Note>
+`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>
 
-## Generated methods
+## Product methods
 
-Each data model gets a standard set of auto-generated methods. For `Product`:
+These methods act on `Product`:
 
-| Method | Description |
+| Method | Signature |
 | --- | --- |
-| `createProducts(data)` | Create one or more products |
-| `retrieveProduct(id, config?)` | Retrieve a product by id |
-| `listProducts(filters?, config?)` | List products matching filters |
-| `listAndCountProducts(filters?, config?)` | List products with a total count |
-| `updateProducts(data)` | Update one or more products |
-| `deleteProducts(ids)` | Delete one or more products |
+| `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>` |
 
-The same set exists for every model in the module, such as `ProductVariant`,
-`ProductCategory`, `ProductCollection`, `ProductTag`, and `ProductType` (e.g.
-`createProductVariants`, `listProductCategories`, `updateProductCollections`).
+`filters` takes `FilterableProductProps`, such as `id`, `status`, `handle`, or `q`. `config` takes `select`, `relations`, `skip`, `take`, and `order`.
 
-<Warning>
-  Prefer [workflows](/platform/catalog/reference/workflows) for anything with
-  side effects, such as submissions, review transitions, and allowlist changes. The
-  service writes records directly and does **not** run the marketplace layer,
-  emit Mercur's product events, or record the audit trail.
-</Warning>
+## 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.