@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/platform/attribute/concepts/variant-axes.mdx

@@ -0,0 +1,61 @@
+---
+title: "Variant axes"
+sidebarTitle: "Variant axes"
+description: "How is_variant_axis mirrors a native ProductOption and generates variants."
+---
+
+In this document, you'll learn how an attribute becomes the axis a product's
+variants are generated from, and the mirror links that keep the two in sync.
+
+## Variant-axis attribute
+
+A `multi_select` attribute marked `is_variant_axis` is more than a descriptor.
+It defines a dimension along which a product varies, such as Size or Color. When
+such an attribute is created, the `ProductAttribute` model records the id of a native
+Medusa `ProductOption` in its `product_option_id` field, and each of its
+`ProductAttributeValue`s records the matching `ProductOptionValue` id in
+`product_option_value_id`.
+
+```ts
+await createProductAttributesWorkflow(container).run({
+  input: {
+    attributes: [
+      {
+        name: "Size",
+        type: "multi_select",
+        is_variant_axis: true,
+        values: [{ name: "S" }, { name: "M" }, { name: "L" }],
+      },
+    ],
+  },
+})
+```
+
+Because the attribute mirrors a real `ProductOption`, the values a product
+selects along that axis are exactly what Medusa uses to generate its variants.
+
+## Mirror links
+
+The attribute catalog and Medusa's product options are two separate modules, so
+the relationship is kept as a pair of **read-only mirror links**:
+
+| Mirror | FK on the attribute side | Points to |
+| --- | --- | --- |
+| Attribute → option | `ProductAttribute.product_option_id` | `ProductOption` |
+| Value → option value | `ProductAttributeValue.product_option_value_id` | `ProductOptionValue` |
+
+Both are 1:1 and have no pivot table. The foreign key lives on the attribute
+record itself.
+
+<Note>
+  The mirror links are **read-only**. They're resolved from the FK on the
+  attribute record; you never write the relationship through the link. The
+  workflows keep the option and the attribute in step whenever an axis attribute
+  or its values change.
+</Note>
+
+<Tip>
+  Only `multi_select` attributes can be variant axes. The other four types
+  (`single_select`, `text`, `unit`, `toggle`) describe a product but never
+  generate variants.
+</Tip>

package/content/platform/attribute/guides/attach-attributes-to-a-product.mdx

@@ -0,0 +1,69 @@
+---
+title: "Attach attributes to a product"
+sidebarTitle: "Attach to a product"
+description: "Attach, detach, and update a product's attributes in one batch call."
+---
+
+In this guide, you'll learn how to manage all of a product's attributes from
+server code through a single batch workflow.
+
+Mercur exposes `createAndLinkProductAttributesToProductWorkflow`, the engine
+behind the product attribute batch endpoint. One call can attach new attributes,
+detach existing ones, and update selections, applied in the order
+**remove → add → update** so a same-call remove and re-add of one attribute
+resolves correctly.
+
+## Run the batch workflow
+
+```ts title="src/api/custom/products/[id]/attributes/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createAndLinkProductAttributesToProductWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
+    input: {
+      product_id: req.params.id,
+      add: [
+        // Existing select attribute: link chosen values
+        { id: "pattr_material", value_ids: ["pattrval_cotton"] },
+        // Existing text / unit / toggle attribute: set a scalar
+        { id: "pattr_thread_count", value: 400 },
+        // Inline attribute created and attached in one step
+        { title: "Gift wrap", type: "toggle", value: true },
+      ],
+      remove: ["pattr_legacy_field"],
+      update: [{ id: "pattr_color", add: ["pattrval_blue"], remove: ["pattrval_red"] }],
+    },
+  })
+
+  res.sendStatus(200)
+}
+```
+
+## The three operations
+
+Each entry in `add` is one of the `ProductAttributeBatchAdd` forms:
+
+| Form | Shape | Effect |
+| --- | --- | --- |
+| Existing select / axis | `{ id, value_ids }` | Links the referenced values to the product |
+| Existing text / unit / toggle | `{ id, value }` | `text`/`unit` create and link a value; `toggle` links the seeded `true`/`false` value |
+| Inline axis | `{ title, values, is_variant_axis: true }` | Creates an exclusive option, a scoped attribute, and the value mirror |
+| Inline non-axis | `{ title, type, value \| values }` | Creates a scoped attribute plus its value(s) and links them |
+
+`remove` takes attribute ids to detach; `update` carries
+`ProductAttributeBatchUpdate` entries adjusting an existing selection.
+
+<Note>
+  For a variant-axis attribute, `value_ids` is the per-product **subset** of the
+  mirror option's values. The product's variants are generated from exactly that
+  subset. See [Variant axes](/platform/attribute/concepts/variant-axes).
+</Note>
+
+<Tip>
+  The batch workflow composes the lower-level
+  `addProductAttributesToProductWorkflow`,
+  `removeProductAttributesFromProductWorkflow`, and
+  `updateProductAttributesOnProductWorkflow`. Reach for those directly when you
+  only need one of the three operations.
+</Tip>

package/content/platform/attribute/guides/create-a-variant-axis.mdx

@@ -0,0 +1,83 @@
+---
+title: "Create a variant axis"
+sidebarTitle: "Create a variant axis"
+description: "Generate product variants from a multi_select axis attribute."
+---
+
+In this guide, you'll learn how to create a variant-axis attribute and use it to
+generate a product's variants from server code.
+
+A variant axis is a `multi_select` attribute with `is_variant_axis` set. Creating
+one mirrors a native Medusa `ProductOption`, so the values a product selects along
+the axis become the dimensions Medusa uses to generate variants.
+
+## Create the axis attribute
+
+```ts title="src/api/custom/attributes/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createProductAttributesWorkflow(req.scope).run({
+    input: {
+      attributes: [
+        {
+          name: "Size",
+          type: "multi_select",
+          is_variant_axis: true,
+          is_filterable: true,
+          values: [{ name: "S" }, { name: "M" }, { name: "L" }],
+        },
+      ],
+    },
+  })
+
+  res.status(201).json({ attribute: result[0] })
+}
+```
+
+The workflow creates the `ProductAttribute`, a mirror `ProductOption`, and a
+`ProductAttributeValue` for each option value. It wires `product_option_id` and
+`product_option_value_id` behind the scenes.
+
+## Attach it to a product
+
+Attach the axis to a product and pass the subset of values that product offers.
+Medusa generates a variant for each selected value.
+
+```ts
+import { createAndLinkProductAttributesToProductWorkflow } from "@mercurjs/core/workflows"
+
+await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
+  input: {
+    product_id: "prod_shirt",
+    add: [{ id: "pattr_size", value_ids: ["pattrval_s", "pattrval_m"] }],
+  },
+})
+```
+
+<Note>
+  Only `multi_select` attributes can be variant axes. The `value_ids` you pass
+  are the per-product subset of the axis's values. Only those become variants.
+</Note>
+
+## Inline axes
+
+To create a product-scoped axis in the same step it's attached, pass the inline
+form instead of an existing id. This creates an exclusive `ProductOption`, a
+scoped attribute (`product_id` set), and the value mirror in one call:
+
+```ts
+await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
+  input: {
+    product_id: "prod_shirt",
+    add: [{ title: "Cut", is_variant_axis: true, values: ["Slim", "Regular"] }],
+  },
+})
+```
+
+<Tip>
+  Inline axes are ideal for a one-off dimension a single product needs. Reach for
+  a global axis attribute when the same dimension, such as Size or Color, recurs
+  across the catalog. See [Global vs inline](/platform/attribute/concepts/global-vs-inline).
+</Tip>

package/content/platform/attribute/guides/create-an-attribute.mdx

@@ -0,0 +1,81 @@
+---
+title: "Create an attribute"
+sidebarTitle: "Create an attribute"
+description: "Create a typed catalog attribute with createProductAttributesWorkflow."
+---
+
+In this guide, you'll learn how to create a global catalog attribute from your
+own server code, for example in a seed script, a custom API route, or a catalog
+import.
+
+Mercur exposes a `createProductAttributesWorkflow` that creates one or more
+`ProductAttribute` records along with their values. Run it from any place that
+has access to the Medusa container.
+
+## Run the workflow
+
+```ts title="src/api/custom/attributes/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createProductAttributesWorkflow(req.scope).run({
+    input: {
+      attributes: [
+        {
+          name: "Material",
+          type: "single_select",
+          is_filterable: true,
+          values: [{ name: "Cotton" }, { name: "Wool" }, { name: "Linen" }],
+        },
+      ],
+    },
+  })
+
+  res.status(201).json({ attribute: result[0] })
+}
+```
+
+The workflow creates the attribute, its `ProductAttributeValue` records, and,
+for a `multi_select` axis, the mirror `ProductOption`. It also emits the
+`product-attribute.created` event.
+
+<Note>
+  Leaving `product_id` unset creates a **global** attribute reusable across the
+  catalog. Passing a `product_id` creates an **inline** attribute scoped to a
+  single product. See [Global vs inline](/platform/attribute/concepts/global-vs-inline).
+</Note>
+
+## Associate categories
+
+Pass `category_ids` on an attribute to associate it with product categories
+through the category link in the same call:
+
+```ts
+await createProductAttributesWorkflow(req.scope).run({
+  input: {
+    attributes: [
+      {
+        name: "Thread count",
+        type: "unit",
+        category_ids: ["pcat_bedding"],
+      },
+    ],
+  },
+})
+```
+
+## Attach custom data
+
+The workflow accepts an `additional_data` payload passed to its
+`productAttributesCreated` hook, letting you persist marketplace-specific data
+alongside the attribute without forking the workflow.
+
+```ts
+await createProductAttributesWorkflow(req.scope).run({
+  input: {
+    attributes: [{ name: "Material", type: "single_select" }],
+    additional_data: { imported_from: "legacy-pim" },
+  },
+})
+```

package/content/platform/attribute/overview.mdx

@@ -0,0 +1,87 @@
+---
+title: "Attribute"
+sidebarTitle: "Overview"
+description: "An operator-managed, typed attribute catalog for describing and filtering the shared product catalog."
+---
+
+Use Mercur to define a typed vocabulary for your products, such as colors,
+materials, sizes, capacities, or warranty toggles, and reuse it across the whole
+marketplace.
+
+The Attribute domain is an operator-managed catalog of typed fields that attach
+to products in the shared master catalog. Attributes describe products
+consistently and drive storefront filters. For variant axes, they generate the
+product variants shoppers pick between. Every attribute is one of five types.
+Each one is either a global catalog entry reused everywhere or an inline field
+scoped to a single product.
+
+<Note>
+  **Attribute = the `ProductAttribute` entity.** The catalog is owned by the
+  Product Attribute module (`MercurModules.PRODUCT_ATTRIBUTE`, id prefix
+  `pattr`). Products are the shared master catalog. Attributes never belong to a
+  store. Sellers list against master products through offers.
+</Note>
+
+## Key features
+
+- **Five typed forms:** `single_select`, `multi_select`, `text`, `unit`, and `toggle`, each with its own validation and UI shape.
+- **Variant axes:** a `multi_select` attribute marked `is_variant_axis` mirrors a native Medusa `ProductOption` and generates product variants.
+- **Global or inline:** reuse a global catalog attribute across products, or attach a one-off attribute scoped to a single product.
+- **Storefront filtering:** an `is_filterable` flag exposes an attribute as a shopper-facing facet.
+- **Batch attach:** attach, detach, and update all of a product's attributes through a single engine workflow.
+- **Ordered and governed:** `rank`, `is_active`, and `is_required` control ordering, availability, and required-field enforcement.
+
+## Get started
+
+Learn how the domain fits together.
+
+<CardGroup cols={2}>
+  <Card title="Attribute types" icon="shapes" href="/platform/attribute/concepts/attribute-types">
+    The five attribute types and the values they hold.
+  </Card>
+  <Card title="Variant axes" icon="sitemap" href="/platform/attribute/concepts/variant-axes">
+    How `is_variant_axis` mirrors a `ProductOption` and generates variants.
+  </Card>
+  <Card title="Global vs inline" icon="layer-group" href="/platform/attribute/concepts/global-vs-inline">
+    Catalog-wide attributes, product-scoped attributes, and filtering.
+  </Card>
+</CardGroup>
+
+## Examples
+
+Build against the Attribute domain in your own code.
+
+<CardGroup cols={2}>
+  <Card title="Create an attribute" icon="plus" href="/platform/attribute/guides/create-an-attribute">
+    Run `createProductAttributesWorkflow` from a route or seed script.
+  </Card>
+  <Card title="Attach to a product" icon="link" href="/platform/attribute/guides/attach-attributes-to-a-product">
+    Attach, detach, and update attributes in one batch call.
+  </Card>
+  <Card title="Create a variant axis" icon="sitemap" href="/platform/attribute/guides/create-a-variant-axis">
+    Generate variants from a `multi_select` axis attribute.
+  </Card>
+</CardGroup>
+
+## Resources
+
+Data models, links, workflows, service methods, and events for the Attribute
+domain.
+
+<CardGroup cols={2}>
+  <Card title="Data models" icon="table" href="/platform/attribute/reference/data-models">
+    The `ProductAttribute` and `ProductAttributeValue` entities.
+  </Card>
+  <Card title="Links" icon="link" href="/platform/attribute/reference/links">
+    How the Attribute domain links to products, categories, and options.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/platform/attribute/reference/workflows">
+    Catalog and product-attachment workflows.
+  </Card>
+  <Card title="Service" icon="gear" href="/platform/attribute/reference/service">
+    Module service methods for working with records directly.
+  </Card>
+  <Card title="Events" icon="bell" href="/platform/attribute/reference/events">
+    Events emitted as attributes and values change.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,56 @@
+---
+title: "Data models"
+sidebarTitle: "Data models"
+description: "The data models owned by the Attribute (Product Attribute) domain."
+---
+
+The Attribute domain is owned by the **Product Attribute module**. This reference
+lists its data models and their fields. For the full module overview, see the
+[Attribute module overview](/platform/attribute/overview).
+
+## ProductAttribute
+
+Table `product_attribute`, id prefix `pattr`. A typed catalog attribute.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `name` | text | Searchable |
+| `handle` | text | Nullable; unique when set |
+| `description` | text | Nullable |
+| `type` | enum | `AttributeType`: `single_select`, `multi_select`, `text`, `unit`, `toggle` |
+| `is_required` | boolean | Default `false` |
+| `is_filterable` | boolean | Default `false`; exposes the attribute as a storefront filter |
+| `is_variant_axis` | boolean | Default `false`; `multi_select` axis that generates variants |
+| `rank` | number | Default `0`; ordering |
+| `is_active` | boolean | Default `true` |
+| `created_by` | text | Nullable |
+| `product_id` | text | Nullable; non-null = product-scoped (inline), null = global |
+| `product_option_id` | text | Nullable; FK to the mirror `ProductOption` (axis attributes) |
+| `metadata` | json | Nullable |
+
+Relations: `values` (one-to-many `ProductAttributeValue`, deleted with the
+attribute).
+
+## ProductAttributeValue
+
+Table `product_attribute_value`, id prefix `pattrval`. A selectable value that
+belongs to one attribute.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `name` | text | The value label |
+| `handle` | text | Nullable; unique per attribute when set |
+| `rank` | number | Default `0`; ordering |
+| `is_active` | boolean | Default `true` |
+| `product_option_value_id` | text | Nullable; FK to the mirror `ProductOptionValue` (axis values) |
+| `metadata` | json | Nullable |
+
+Relations: `attribute` (belongs to `ProductAttribute` via `attribute_id`).
+
+<Note>
+  `product_option_id` on the attribute and `product_option_value_id` on the value
+  are the foreign keys behind the read-only mirror links to Medusa's product
+  options. See [Links](/platform/attribute/reference/links).
+</Note>

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

@@ -0,0 +1,41 @@
+---
+title: "Event reference"
+sidebarTitle: "Events"
+description: "Events emitted by the Attribute domain, for subscribers and side effects."
+---
+
+The Attribute domain emits events as attributes and their values change.
+Subscribe to them to run side effects, such as reindexing storefront filters,
+syncing an external PIM, or kicking off follow-up workflows, instead of polling.
+
+```ts title="src/subscribers/attribute-created.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function attributeCreatedHandler({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const attributeId = event.data.id
+  // ...reindex filters, sync to an external system, etc.
+}
+
+export const config: SubscriberConfig = {
+  event: "product-attribute.created",
+}
+```
+
+## Attribute events
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-attribute.created` | An attribute is created | `{ id }` |
+| `product-attribute.updated` | An attribute changes | `{ id }` |
+| `product-attribute.deleted` | An attribute is deleted | `{ id }` |
+
+## Value events
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-attribute-value.created` | A value is created | `{ id }` |
+| `product-attribute-value.updated` | A value changes | `{ id }` |
+| `product-attribute-value.deleted` | A value is deleted | `{ id }` |

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

@@ -0,0 +1,45 @@
+---
+title: "Links to other modules"
+sidebarTitle: "Links"
+description: "How the Attribute (Product Attribute) domain links to products, categories, and options."
+---
+
+Modules in Mercur never reference each other directly. They're connected through
+**module links**. The Product Attribute module links into Medusa's product module
+in several ways: to products, to categories, and, for variant axes, to product
+options through mirror links. Once a link is defined, you retrieve related records
+with `query.graph` using the link alias.
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "scoped_attributes.*"],
+})
+```
+
+## Products
+
+| Link | Table | Relationship |
+| --- | --- | --- |
+| **Product → attribute** (`scoped_attributes`) | None | Read-only; a product's inline (product-scoped) attributes, resolved from `ProductAttribute.product_id` |
+| **Product ↔ attribute value** | `product_attribute_value_link` | Many-to-many pivot; the values selected on a product |
+
+## Categories
+
+| Link | Table | Relationship |
+| --- | --- | --- |
+| **Attribute ↔ category** (`categories`) | `product_category_attribute` | Many-to-many; the product categories an attribute is associated with |
+
+## Product options (mirror links)
+
+| Link | FK | Relationship |
+| --- | --- | --- |
+| **Attribute → option** | `ProductAttribute.product_option_id` | Read-only 1:1; the mirror `ProductOption` for a variant-axis attribute |
+| **Value → option value** | `ProductAttributeValue.product_option_value_id` | Read-only 1:1; the mirror `ProductOptionValue` for an axis value |
+
+<Note>
+  The mirror links (Attribute → option, Value → option value) and the product
+  scope link (`scoped_attributes`) are **read-only**. They're resolved from the
+  FK on the owning record and can't be written through the link itself. The
+  workflows keep the mirror in sync when axis attributes and values change.
+</Note>

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

@@ -0,0 +1,49 @@
+---
+title: "Service reference"
+sidebarTitle: "Service"
+description: "The Product Attribute module service, with methods for working with records directly."
+---
+
+The Product Attribute module exposes a service you can resolve from the Medusa
+container to read and write records directly, without going through a workflow.
+Use it inside custom services, subscribers, or scheduled jobs.
+
+```ts
+import { MercurModules } from "@mercurjs/types"
+
+const attributeModuleService = container.resolve(
+  MercurModules.PRODUCT_ATTRIBUTE,
+)
+
+const [attributes, count] =
+  await attributeModuleService.listAndCountProductAttributes({
+    type: "single_select",
+  })
+```
+
+## Generated methods
+
+Each data model gets a standard set of auto-generated methods. For
+`ProductAttribute`:
+
+| Method | Description |
+| --- | --- |
+| `createProductAttributes(data)` | Create one or more attributes |
+| `retrieveProductAttribute(id, config?)` | Retrieve an attribute by id |
+| `listProductAttributes(filters?, config?)` | List attributes matching filters |
+| `listAndCountProductAttributes(filters?, config?)` | List attributes with a total count |
+| `updateProductAttributes(data)` | Update one or more attributes |
+| `deleteProductAttributes(ids)` | Delete one or more attributes |
+
+The same set exists for `ProductAttributeValue`: `createProductAttributeValues`,
+`retrieveProductAttributeValue`, `listProductAttributeValues`,
+`listAndCountProductAttributeValues`, `updateProductAttributeValues`, and
+`deleteProductAttributeValues`.
+
+<Warning>
+  Prefer [workflows](/platform/attribute/reference/workflows) for anything with
+  side effects, such as creating an axis attribute, attaching attributes to a
+  product, or keeping the mirror `ProductOption` in sync. The service writes records
+  directly and does **not** emit events, maintain the option mirror, or run
+  compensation.
+</Warning>

package/content/platform/attribute/reference/workflows.mdx

@@ -0,0 +1,45 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Attribute catalog and product-attachment workflows."
+---
+
+This reference lists the workflows for the Attribute domain. Import them from
+`@mercurjs/core/workflows` and run them against the Medusa container.
+
+## Catalog workflows
+
+Manage the attribute catalog and its values.
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `createProductAttributesWorkflow` | `{ attributes[], additional_data? }` | Create attributes (+ values, + mirror option for axes) |
+| `updateProductAttributesWorkflow` | `{ selector, update }` | Update attribute fields |
+| `deleteProductAttributesWorkflow` | `{ ids[] }` | Delete attributes (fails if still linked) |
+| `createProductAttributeValuesWorkflow` | `{ values[], additional_data? }` | Add values to attributes |
+| `updateProductAttributeValuesWorkflow` | `{ selector, update }` | Update values |
+| `deleteProductAttributeValuesWorkflow` | `{ ids[] }` | Delete values |
+| `upsertProductAttributeValuesWorkflow` | `{ attribute_id, values[] }` | Create or update an attribute's values in one call |
+
+## Product-attachment workflows
+
+Attach attributes to products in the shared master catalog.
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `createAndLinkProductAttributesToProductWorkflow` | `{ product_id, add?, remove?, update? }` | Batch engine: attach, detach, and update, applied remove → add → update |
+| `addProductAttributesToProductWorkflow` | `{ product_id, add[] }` | Attach attributes (existing or inline) to a product |
+| `removeProductAttributesFromProductWorkflow` | `{ product_id, ... }` | Detach attributes from a product |
+| `updateProductAttributesOnProductWorkflow` | `{ product_id, ... }` | Update a product's attribute selections |
+
+<Note>
+  `createAndLinkProductAttributesToProductWorkflow` is the engine behind the
+  product attribute batch endpoint; it composes the three single-purpose
+  attachment workflows. See
+  [Attach attributes to a product](/platform/attribute/guides/attach-attributes-to-a-product).
+</Note>
+
+To work with records directly instead of through a workflow, see the
+[Service reference](/platform/attribute/reference/service). To run side effects
+when an attribute changes, see the
+[Event reference](/platform/attribute/reference/events).

package/content/platform/catalog/concepts/master-products.mdx

@@ -0,0 +1,54 @@
+---
+title: "Master products"
+sidebarTitle: "Master products"
+description: "The shared catalog, why products aren't seller-owned, and submission attribution."
+---
+
+In this document, you'll learn how Mercur models products as a single shared
+catalog rather than per-seller listings.
+
+## Product
+
+A product is a **master product** in a catalog shared by the whole marketplace,
+represented by Medusa's native `Product` data model (table `product`, id prefix
+`prod`). Products carry the usual commerce fields such as `title`, `handle`,
+`description`, `status`, variants, options, and images, and are **not owned by
+any store**. Creating a product adds it to the shared catalog. Multiple stores
+can then sell the same master product.
+
+```ts
+const { result } = await createProductsWorkflow(container).run({
+  input: {
+    products: [
+      {
+        title: "Aeron Chair",
+        status: "proposed",
+        seller_ids: ["sel_123"],
+      },
+    ],
+    created_by: "usr_123",
+  },
+})
+```
+
+<Note>
+  A store never sells a bare master product directly. It sells against one by
+  creating an [offer](/platform/offer/overview). The offer carries the store's
+  own SKU, price, inventory, and shipping profile, while the master product
+  holds the shared catalog data everyone shares.
+</Note>
+
+## Attribution, not ownership
+
+Because the catalog is shared, the creator of a product does **not** own it.
+When a store submits a new product, Mercur records the submission as an immutable
+audit entry (a `PRODUCT_ADD` action in the product-change pipeline) so you know
+who proposed it. That attribution is for review and history only. Once
+published, the product belongs to the shared catalog like any other.
+
+<Tip>
+  Attribution is recorded automatically by `createProductsWorkflow` through its
+  `created_by` input. You don't manage it by hand. See the
+  [status lifecycle](/platform/catalog/concepts/status-lifecycle) for how a
+  submission becomes a published catalog product.
+</Tip>