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

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

@@ -1,54 +1,56 @@
 ---
-title: "Master products"
+title: "Master products in a shared catalog"
 sidebarTitle: "Master products"
-description: "The shared catalog, why products aren't seller-owned, and submission attribution."
+description: "Why products belong to the marketplace catalog instead of a store, and how Mercur records who submitted each one."
 ---
 
-In this document, you'll learn how Mercur models products as a single shared
-catalog rather than per-seller listings.
+A master product is the one catalog record for an item that any number of stores can sell. Mercur keeps products out of store ownership so that two stores selling the same chair share one title, one set of variants, and one product page, and compete on their offers instead.
 
-## Product
+## One product, sold through offers
 
-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.
+A master product is Medusa's native `Product` model (table `product`, id prefix `prod`). It holds the shared catalog data: `title`, `handle`, `description`, `status`, images, options, variants, and categories. It has no seller column. Creating a product adds it to the catalog, and stores then sell it by creating [offers](/platform/offer/overview) against its variants.
+
+The split between the two records works like this:
+
+- **Master product**: what the item is, shared by every store that sells it
+- **Offer**: how one store sells it, with the store's own SKU, price, stock, and shipping profile
+
+A store's stock and price never live on the variant. Offer inventory links to the offer, so a variant's `inventory_items` stay empty for marketplace sales.
+
+## Attribution instead of ownership
+
+Mercur records who submitted a product without making them its owner. `createProductsWorkflow` takes a required `created_by` and writes a confirmed `ProductChange` with that value as `created_by`, holding one `PRODUCT_ADD` action. The action's `details` store the starting `status` and the ids of the attributes the product began with.
+
+The vendor API passes the store's seller id as `created_by`, and the admin API passes the operator's user id. Mercur reads that record back to decide which products a store submitted:
 
 ```ts
-const { result } = await createProductsWorkflow(container).run({
-  input: {
-    products: [
-      {
-        title: "Aeron Chair",
-        status: "proposed",
-        seller_ids: ["sel_123"],
-      },
-    ],
-    created_by: "usr_123",
+const { data: actions } = await query.graph({
+  entity: "product_change_action",
+  fields: ["product_id"],
+  filters: {
+    action: "PRODUCT_ADD",
+    product_change: { created_by: "sel_01JD8Q1234567" },
   },
 })
 ```
 
+The query returns the ids of every product the store submitted. Mercur runs the same lookup to let a store see its own `draft` and `proposed` submissions, which other stores never see.
+
 <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.
+  Attribution grants visibility, not control of the catalog entry. Every edit a store makes through the vendor API, to its own submission or to a published product, goes through the [product edit pipeline](/platform/product-edit/overview).
 </Note>
 
-## Attribution, not ownership
+## What a store sees
+
+The vendor API filters product reads by status, attribution, and the [allowlist](/platform/catalog/concepts/product-seller-allowlist). A store's product list contains:
+
+- **Its own submissions**: products it created that are `draft` or `proposed`
+- **Published products open to it**: `published` products whose allowlist is empty or includes the store
+
+A store can still read one of its own `rejected` products by id, but rejected products drop out of its list. The Store API returns `published` products only.
 
-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.
+## Related
 
-<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>
+- [Status lifecycle](/platform/catalog/concepts/status-lifecycle) for how a submission becomes a published product
+- [Create a master product](/platform/catalog/guides/create-a-master-product) to run the create workflow from your code
+- [Offers](/platform/offer/overview) for how stores sell a master product

package/content/platform/catalog/concepts/product-seller-allowlist.mdx

@@ -1,48 +1,69 @@
 ---
-title: "The store allowlist"
+title: "Restrict a product to chosen stores"
 sidebarTitle: "The allowlist"
-description: "The product_seller link that controls which stores may sell a master product."
+description: "How the product_seller link opens a product to every store or restricts it to the stores on its list."
 ---
 
-In this document, you'll learn how Mercur controls which stores are allowed to
-sell a shared master product.
+The store allowlist decides which stores can see and sell a published master product. It's a many-to-many link between Medusa's `Product` and Mercur's `Seller`, stored in the `product_seller` table. Use it for exclusive ranges, brand-authorized resellers, or products only certain stores may carry.
 
-## Product seller
+## Open by default, restricted by rows
 
-Since the catalog is shared, Mercur needs a way to say *which* stores may sell a
-given master product. That's the **product–seller allowlist**: a many-to-many
-link between Medusa's `Product` and Mercur's `Seller`, stored in the
-`product_seller` table.
+A product's allowlist has two states, and the number of `product_seller` rows decides which one applies. An empty allowlist doesn't block anyone: it means every store can sell the product.
+
+| `product_seller` rows | Who can see and sell the published product |
+| --- | --- |
+| None | Every store |
+| One or more | Only the stores on the list |
+
+Adding the first store to a product's allowlist closes it to every other store. Removing the last store opens it to all stores again.
+
+## Read a product's allowlist
+
+The link exposes the stores under the `sellers` alias on a product. Read it with `query.graph`:
 
 ```ts
-const { data: products } = await query.graph({
+const { data: [product] } = await query.graph({
   entity: "product",
   fields: ["id", "title", "sellers.id", "sellers.name"],
-  filters: { id: "prod_123" },
+  filters: { id: "prod_01JD8Q1234567" },
 })
+
+const isOpen = (product.sellers ?? []).length === 0
 ```
 
-A store appears in a product's `sellers` list only if it has been allowlisted.
-Being on the allowlist is what lets a store create an
-[offer](/platform/offer/overview) against the master product. Without it, the
-store cannot list that product for sale.
-
-<Note>
-  The allowlist link is created automatically for the submitting store when a
-  product is created with `seller_ids`, and managed afterwards with
-  `linkSellersToProductWorkflow`. See
-  [Allowlist stores](/platform/catalog/guides/allowlist-stores).
-</Note>
-
-## Category allowlist
-
-Product categories carry the same pattern through the `category_seller` link. It
-is a many-to-many association between `ProductCategory` and `Seller` that scopes
-which categories a store is associated with. Manage it with
-`linkSellersToProductCategoryWorkflow`.
-
-<Tip>
-  The allowlist governs the **right to sell**, not the sale itself. A store on
-  the allowlist still has to create an offer to actually list the product.
-  Allowlisting alone doesn't put anything on the storefront.
-</Tip>
+An empty `sellers` array means the product is open to every store. You can also query the link table directly as the `product_seller` entity, with `product_id` and `seller_id` fields.
+
+## Where Mercur enforces it
+
+Mercur applies the allowlist when it scopes a store's view of the catalog. These vendor reads hide a published product restricted to other stores:
+
+- **Product list and detail**: the product returns `404` for a store not on its list
+- **Variant list**: variants of restricted products are filtered out
+- **Product variants under a product**: blocked with the product itself
+
+A store always sees its own `draft` and `proposed` submissions, whatever their allowlist. The admin API and the Store API don't filter by allowlist.
+
+<Warning>
+  `createOffersWorkflow` doesn't check the allowlist. If you create offers from your own server code, check the product's `sellers` first, or a store can sell a product it isn't allowed to.
+</Warning>
+
+## How stores get on the list
+
+Mercur writes `product_seller` rows in two places:
+
+- **On create**: `createProductsWorkflow` links every id in a product's `seller_ids` input
+- **Afterwards**: `linkSellersToProductWorkflow` adds and removes stores in one run
+
+The vendor API never passes `seller_ids`, so a store's own submission starts open to every store. An operator restricts it with `linkSellersToProductWorkflow`. Removing a store from the list doesn't touch the offers it already created.
+
+## The category_seller link
+
+Categories have a second link to stores, `category_seller`, between `ProductCategory` and `Seller` with the `sellers` alias on a category. `linkSellersToProductCategoryWorkflow` writes it.
+
+No shipped route or workflow reads the link to filter products. Mercur exports `validateSellerProductPermissionsStep`, which throws `Seller is restricted from categories` when the seller is linked to any of the category ids you pass. Add that step to your own workflow if you treat the link as a category block list.
+
+## Related
+
+- [Allowlist stores](/platform/catalog/guides/allowlist-stores) to manage the list from your code
+- [Master products](/platform/catalog/concepts/master-products) for what a store sees by default
+- [Links reference](/platform/catalog/reference/links) for every link on products and categories

package/content/platform/catalog/concepts/status-lifecycle.mdx

@@ -1,58 +1,64 @@
 ---
-title: "Status lifecycle"
+title: "Product status lifecycle"
 sidebarTitle: "Status lifecycle"
-description: "How a master product moves from draft to proposed, published, or rejected."
+description: "How a master product moves from draft or proposed to published or rejected, and which workflow runs each step."
 ---
 
-In this document, you'll learn about the product status lifecycle and how a
-submission becomes a live catalog product.
+Every master product has a `status` that decides who can see it and whether it's for sale. Mercur uses that status as a review gate: stores submit products as `proposed`, and an operator decides whether each one joins the published catalog.
 
-## Status
+## The four statuses
 
-A product's state is held in the `status` field of the `Product` model, typed by
-Medusa's `ProductStatus` enum. A master product moves through four statuses:
+The status lives in the `status` field of Medusa's `Product` model. Mercur re-exports the values as `ProductStatus` from `@mercurjs/types`. The model default is `draft`.
 
+| Status | Meaning | Who sees it |
+| --- | --- | --- |
+| `draft` | Work in progress, not submitted | Operators and the submitting store |
+| `proposed` | Submitted and waiting for review | Operators and the submitting store |
+| `published` | Live in the shared catalog | Everyone the [allowlist](/platform/catalog/concepts/product-seller-allowlist) permits, and the Store API |
+| `rejected` | Turned down in review | Operators, and the submitting store by id |
+
+## Review transitions
+
+Mercur ships one workflow per review step. Each one reads the product, checks its status with `validateProductsStatusStep`, records a confirmed `ProductChange`, and emits an event.
+
+<img className="block dark:hidden" src="/images/figures/catalog-status-lifecycle-light.svg" alt="A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind." />
+<img className="hidden dark:block" src="/images/figures/catalog-status-lifecycle-dark.svg" alt="A Status transitions table: createProductsWorkflow creates a product as proposed, then confirmProductsWorkflow, rejectProductWorkflow, and requestProductChangeWorkflow move it to published, to rejected, or keep it proposed, with a product_change audit table behind." />
+
+| Workflow | From | To | Audit action | Event |
+| --- | --- | --- | --- | --- |
+| `createProductsWorkflow` | none | input `status` | `PRODUCT_ADD` | `product.created` |
+| `confirmProductsWorkflow` | `proposed` | `published` | `STATUS_CHANGE` | `product.published` |
+| `rejectProductWorkflow` | `proposed` | `rejected` | `STATUS_CHANGE` | `product.rejected` |
+| `requestProductChangeWorkflow` | `proposed` | `proposed` | `CHANGE_REQUESTED` | `product.change-requested` |
+
+The three review workflows run only on `proposed` products. A product in any other status fails with a `NOT_ALLOWED` error that lists each product id and its current status.
+
+## Starting status
+
+The status a product starts in depends on who creates it. `createProductsWorkflow` passes the `status` you give it to Medusa, which falls back to `draft`.
+
+- **Vendor API**: defaults to `proposed`; a store may also send `draft`
+- **Admin API**: uses the request's `status`, or `draft` when it has none
+- **Your own code**: whatever you pass, or `draft`
+
+The vendor rule comes from the `product_request` feature flag, which is on by default. Turn it off with `MEDUSA_FF_PRODUCT_REQUEST=false` and stores can create products in any status, including `published`.
+
+```bash title=".env"
+MEDUSA_FF_PRODUCT_REQUEST=false
 ```
-   ┌────────┐   submit    ┌──────────┐   approve   ┌────────────┐
-   │ draft   │ ──────────►│ proposed  │ ──────────►│ published  │
-   └────────┘             └────┬─────┘             └────────────┘
-                               │ reject
-                               ▼
-                         ┌────────────┐
-                         │ rejected   │
-                         └────────────┘
-```
 
-| Status | Meaning |
-| --- | --- |
-| `draft` | Work in progress, not yet submitted for review |
-| `proposed` | Submitted, awaiting operator review |
-| `published` | Approved and live in the shared catalog, sellable via offers |
-| `rejected` | Turned down during review |
-
-<Note>
-  Vendor-created products default to **`proposed`**. A store submits a product
-  for review rather than publishing it directly. An operator (or a low-risk
-  auto-confirm rule) is what promotes it to `published`.
-</Note>
-
-## Transitions
-
-Each review transition has a dedicated Mercur workflow so the audit trail,
-events, and side effects run consistently:
-
-| Workflow | Transition |
-| --- | --- |
-| `confirmProductsWorkflow` | `proposed` → `published` |
-| `rejectProductWorkflow` | `proposed` → `rejected` |
-| `requestProductChangeWorkflow` | stays `proposed`, asks the submitter for a revision |
-
-Every transition validates that the product is currently `proposed` before it
-runs, and records an immutable `STATUS_CHANGE` (or `CHANGE_REQUESTED`) action in
-the product-change pipeline for a full history of who reviewed what.
-
-<Tip>
-  Reviewing a product doesn't touch offers. Publishing makes the master product
-  sellable, but each store still lists it independently through its own
-  [offer](/platform/offer/overview).
-</Tip>
+The same flag controls whether store edits to existing products wait for review. See [status and auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm).
+
+## Changes outside the review workflows
+
+Mercur ships no workflow that moves a `draft` to `proposed`, or a `published` product back. Those changes go through a regular product update. The admin API runs Medusa's `updateProductsWorkflow` for that, which accepts any status.
+
+<Warning>
+  A direct status update skips the `proposed` check, writes no `STATUS_CHANGE` record, and emits none of Mercur's product events. Use the review workflows when you need the audit trail.
+</Warning>
+
+## Related
+
+- [Publish or reject a product](/platform/catalog/guides/publish-or-reject-a-product) to run the review workflows
+- [Workflows reference](/platform/catalog/reference/workflows) for inputs and hooks
+- [Change pipeline](/platform/product-edit/concepts/change-pipeline) for how edits to existing products are reviewed

package/content/platform/catalog/concepts/variants-categories-collections.mdx

@@ -1,49 +1,69 @@
 ---
-title: "Variants, categories & collections"
+title: "Variants, categories, and collections"
 sidebarTitle: "Variants & categories"
-description: "The native Medusa Product structure the shared catalog is built on."
+description: "The Medusa Product module models that structure the shared catalog, and the places Mercur extends them."
 ---
 
-In this document, you'll learn about the structural models that organize the
-shared catalog, all of them native to Medusa's Product module.
+The shared catalog is built from Medusa's Product module models. Variants describe what a customer can buy, and categories, collections, tags, and types organize products for browsing. Mercur keeps these models as they are and changes how variants get their options and where a variant's price and stock come from.
 
-## Product variant
+## Variants come from attributes
 
-A variant is a purchasable configuration of a master product, represented by the
-`ProductVariant` data model (table `product_variant`, id prefix `variant`).
-Variants are generated from a product's options, including Mercur attributes
-marked as variant axes, and hold the SKU-level structure of the catalog entry.
+A variant is one purchasable configuration of a master product: Medusa's `ProductVariant` model (id prefix `variant`). Each variant binds to one value of every product option, such as Size `M`.
+
+When you create a product through Mercur's `createProductsWorkflow`, you don't pass native `options`. You pass Mercur `attributes`, and every `multi_select` attribute marked `is_variant_axis` becomes a native `ProductOption`. Each variant then names its option values by title:
 
 ```ts
-const { data: products } = await query.graph({
-  entity: "product",
-  fields: ["id", "title", "variants.id", "variants.title", "options.*"],
-  filters: { id: "prod_123" },
-})
+const product = {
+  title: "Linen shirt",
+  attributes: [
+    { title: "Size", is_variant_axis: true, values: ["S", "M"] },
+  ],
+  variants: [
+    { title: "S", options: { Size: "S" } },
+    { title: "M", options: { Size: "M" } },
+  ],
+}
 ```
 
-<Note>
-  Offer-based inventory and pricing live on the [offer](/platform/offer/overview),
-  not the variant. The variant defines the shared catalog structure. Each store's
-  stock and price come from its own offer.
-</Note>
+Medusa requires every product to have at least one option. Mercur creates each product with an internal `__default__` option and removes it once a variant-axis attribute attaches a real one. Products without an axis keep it.
+
+## Price and stock live on offers
+
+A variant holds catalog data such as `title`, `sku`, `ean`, and dimensions. It doesn't hold a store's price or stock. Mercur's create workflow sets `manage_inventory` to `false` on new variants unless you pass it, because each store's stock lives on its [offer](/platform/offer/overview).
 
-## Categories & collections
+- **Price**: an offer-scoped price on the variant's price set, matched by an `offer_id` rule
+- **Stock**: inventory items linked to the offer, not the variant
+- **SKU**: the store's own SKU on the offer, unique per store
+
+## Grouping models
 
 Products are organized with Medusa's native grouping models:
 
-| Model | Purpose |
-| --- | --- |
-| `ProductCategory` | Hierarchical, nestable classification (id prefix `pcat`) |
-| `ProductCollection` | Flat, curated grouping (id prefix `pcol`) |
-| `ProductTag` | Free-form labels for filtering |
-| `ProductType` | A single type classification per product |
-
-Assign products to a category with `assignProductsToCategoryWorkflow`, which
-keeps each product in exactly one category at a time.
-
-<Tip>
-  Categories participate in the marketplace layer too: the `category_seller`
-  link scopes which stores a category is associated with, mirroring the product
-  [allowlist](/platform/catalog/concepts/product-seller-allowlist).
-</Tip>
+| Model | Id prefix | Shape | Mercur extension |
+| --- | --- | --- | --- |
+| `ProductCategory` | `pcat` | Nested tree through `parent_category` | `media_images`, `sellers`, attribute link |
+| `ProductCollection` | `pcol` | Flat group, one per product | `media_images` |
+| `ProductTag` | `ptag` | Free-form labels, many per product | None |
+| `ProductType` | `ptyp` | One type per product | None |
+
+Categories and collections link to Mercur's media module through `media_images` for gallery and icon images. A category also links to stores through `category_seller` and to product attributes through `product_category_attribute`. See the [links reference](/platform/catalog/reference/links).
+
+## One category per product
+
+Medusa lets a product belong to several categories. Mercur's `assignProductsToCategoryWorkflow` keeps one category per product: adding a product to a category replaces the categories it had.
+
+```ts
+import { assignProductsToCategoryWorkflow } from "@mercurjs/core/workflows"
+
+await assignProductsToCategoryWorkflow(container).run({
+  input: { id: "pcat_01JD8Q1234567", add: ["prod_01JD8Q1234567"] },
+})
+```
+
+The product now belongs only to `pcat_01JD8Q1234567`. Passing a product id in `remove` clears all its categories, not only this one.
+
+## Related
+
+- [Attributes](/platform/attribute/overview) for attribute types and variant axes
+- [Data models](/platform/catalog/reference/data-models) for every field on these models
+- [Offers](/platform/offer/overview) for price and stock per store

package/content/platform/catalog/guides/allowlist-stores.mdx

@@ -1,59 +1,122 @@
 ---
-title: "Allowlist stores"
+title: "Restrict a product to chosen stores"
 sidebarTitle: "Allowlist stores"
-description: "Grant and revoke a store's right to sell a master product from server code."
+description: "Add stores to a product's allowlist, remove them, and open a product to every store again from server code."
 ---
 
-In this guide, you'll learn how to control which stores may sell a shared master
-product by managing the `product_seller` allowlist from your own server code.
+Run `linkSellersToProductWorkflow` to change which stores can see and sell a master product. Use it for exclusive ranges, authorized resellers, or to restrict a store's own submission after review.
 
-A store can only create an [offer](/platform/offer/overview) against a master
-product if it's on that product's allowlist. Mercur exposes
-`linkSellersToProductWorkflow` to add and remove stores in a single call.
+## Before you begin
 
-## Add and remove stores
+Know how the list behaves before you change it:
 
-```ts title="src/api/custom/allowlist/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { linkSellersToProductWorkflow } from "@mercurjs/core/workflows"
+- **Empty list**: every store can sell the product
+- **One or more stores**: only those stores can sell it
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  await linkSellersToProductWorkflow(req.scope).run({
-    input: {
-      id: req.params.id, // product id
-      add: ["sel_123", "sel_456"],
-      remove: ["sel_789"],
-    },
-  })
+Read [the store allowlist](/platform/catalog/concepts/product-seller-allowlist) for where Mercur enforces it.
 
-  res.sendStatus(200)
+## Change a product's allowlist
+
+<Steps>
+  <Step title="Add a route that runs the workflow">
+    The workflow takes the product `id` and optional `add` and `remove` arrays of seller ids. It writes and deletes `product_seller` rows in one run.
+
+    ```ts title="src/api/admin/exclusive-products/[id]/route.ts"
+    import type {
+      MedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { linkSellersToProductWorkflow } from "@mercurjs/core/workflows"
+
+    type Body = { add?: string[]; remove?: string[] }
+
+    export async function POST(
+      req: MedusaRequest<Body>,
+      res: MedusaResponse
+    ) {
+      await linkSellersToProductWorkflow(req.scope).run({
+        input: { id: req.params.id, ...req.body },
+      })
+
+      res.json({ id: req.params.id })
+    }
+    ```
+
+    If a step fails, the workflow undoes the rows it already changed.
+  </Step>
+  <Step title="Check the result">
+    Read the product's `sellers` to confirm the new list.
+
+    ```ts
+    const { data: [product] } = await query.graph({
+      entity: "product",
+      fields: ["id", "sellers.id"],
+      filters: { id: "prod_01JD8Q1234567" },
+    })
+    ```
+
+    `product.sellers` holds every store on the list. An empty array means the product is open to all stores.
+  </Step>
+</Steps>
+
+## Open a product to every store again
+
+Remove every store on the list. Read the current stores first, then pass all of them in `remove`.
+
+```ts
+const { data: [product] } = await query.graph({
+  entity: "product",
+  fields: ["sellers.id"],
+  filters: { id: "prod_01JD8Q1234567" },
+})
+
+await linkSellersToProductWorkflow(container).run({
+  input: {
+    id: "prod_01JD8Q1234567",
+    remove: (product.sellers ?? []).map((seller) => seller.id),
+  },
+})
+```
+
+The product now has no `product_seller` rows, so every store can see and sell it once it's published.
+
+## Check the allowlist before creating offers
+
+`createOffersWorkflow` doesn't read the allowlist. If your code creates offers for stores, read the product's `sellers` as shown above and check that the store may sell it first.
+
+```ts
+import { MedusaError } from "@medusajs/framework/utils"
+
+const sellerIds = (product.sellers ?? []).map((seller) => seller.id)
+const allowed =
+  sellerIds.length === 0 || sellerIds.includes("sel_01JD8Q1234567")
+
+if (!allowed) {
+  throw new MedusaError(
+    MedusaError.Types.NOT_ALLOWED,
+    "This store can't sell the product"
+  )
 }
 ```
 
-<Note>
-  `add` and `remove` are both optional. Pass either or both. Adding a store
-  that's already allowlisted is idempotent. Removing a store revokes its right
-  to sell the product going forward.
-</Note>
+`allowed` is true when the list is empty or names the store. Removing a store from the list later doesn't delete the offers it already has.
 
-## Allowlist a category
+## Link stores to a category
 
-Categories use the same shape through `linkSellersToProductCategoryWorkflow`,
-scoping which stores a category is associated with:
+`linkSellersToProductCategoryWorkflow` writes the `category_seller` link with the same input shape.
 
 ```ts
 import { linkSellersToProductCategoryWorkflow } from "@mercurjs/core/workflows"
 
 await linkSellersToProductCategoryWorkflow(container).run({
-  input: {
-    id: "pcat_123",
-    add: ["sel_123"],
-  },
+  input: { id: "pcat_01JD8Q1234567", add: ["sel_01JD8Q1234567"] },
 })
 ```
 
-<Tip>
-  Allowlisting grants the **right to sell**, not the listing itself. After a
-  store is allowlisted, it still has to create an offer for the product to
-  appear on its storefront.
-</Tip>
+Mercur doesn't filter products by this link. Run `validateSellerProductPermissionsStep` in your own workflow if you want linked stores blocked from a category.
+
+## Next steps
+
+- [Create a master product](/platform/catalog/guides/create-a-master-product) with `seller_ids` set from the start
+- [Create an offer](/platform/offer/guides/create-an-offer) for an allowed store
+- [Links reference](/platform/catalog/reference/links) for the `product_seller` and `category_seller` definitions