@mercurjs/docs 2.2.0-canary.40

package/content/resources/tutorials/build-a-block.mdx

@@ -0,0 +1,134 @@
+---
+title: "Build your own block"
+description: "Author a reusable feature as a block — backend, panel UI, and docs — build it into a registry, and install it into any Mercur project."
+---
+
+Blocks are how features travel between Mercur projects: not as npm packages you depend on, but as **source code copied into the target project**. Anything you've built once — a module, workflows, routes, panel pages — can be packaged as a block, published through a registry, and installed with `mercurjs add`. This tutorial builds a minimal "announcements" block and ships it through your own registry.
+
+<Info>
+  **Blocks are source, not dependencies.** When someone installs your block, they get the files — editable, diffable, theirs. Updates are opt-in via `mercurjs diff` and `add --overwrite`, never forced through a lockfile. That's the trade: you give up automatic upgrades, users gain full ownership. Design blocks so they're readable after install.
+</Info>
+
+## What you'll build
+
+An `announcements` block containing a module (data model + service), a vendor API route, and a vendor portal page — built into registry JSON and installed into a Mercur project.
+
+## File types and where they land
+
+Each file in a block carries a `type` that maps to an alias in the consumer's `blocks.json`:
+
+| Type | Lands at (default aliases) |
+|------|---------------------------|
+| `registry:module` | the API package's modules directory |
+| `registry:workflow` | the API package's workflows directory |
+| `registry:api` | `packages/api/src` |
+| `registry:link` | the API package's links directory |
+| `registry:vendor` | `apps/vendor/src` |
+| `registry:admin` | `apps/admin/src` |
+| `registry:lib` | shared lib directory |
+
+## Author and ship the block
+
+<Steps>
+  <Step title="Lay out the block source">
+    A registry is a project with a `registry.json` and block sources under `src/`. Each block follows the standard directory convention, one folder per concern:
+
+    ```
+    my-registry/
+    ├── registry.json
+    └── src/
+        └── announcements/
+            ├── modules/announcements/     # data model, service, index
+            ├── api/vendor/announcements/  # route.ts, validators.ts
+            └── vendor/routes/announcements/
+                └── page.tsx               # vendor portal page
+    ```
+
+    Write the files exactly as they should land in a consumer's project — real imports, real Medusa module definitions. The build step resolves imports and rewrites them to the consumer's path aliases at install time. For the panel page, use the same conventions as any [custom panel page](/rc/resources/tutorials/custom-panel-page): a default export plus a `config` for the sidebar entry.
+  </Step>
+  <Step title="Declare it in registry.json">
+    ```json registry.json
+    {
+      "$schema": "https://registry.mercurjs.com/registry.json",
+      "name": "@my-org",
+      "homepage": "https://my-org.com",
+      "items": [
+        {
+          "name": "announcements",
+          "description": "Marketplace announcements with a vendor portal feed.",
+          "dependencies": [],
+          "registryDependencies": [],
+          "docs": "## Setup\n\nRegister the module in `medusa-config.ts`, then run `bunx medusa db:generate announcements && bunx medusa db:migrate`, and finally `bunx @mercurjs/cli@rc codegen`.",
+          "categories": ["module", "api", "vendor"],
+          "files": [
+            { "path": "announcements/modules/announcements/index.ts", "type": "registry:module" },
+            { "path": "announcements/api/vendor/announcements/route.ts", "type": "registry:api" },
+            { "path": "announcements/vendor/routes/announcements/page.tsx", "type": "registry:vendor" }
+          ]
+        }
+      ]
+    }
+    ```
+
+    Two fields do the heavy lifting: **`type`** on each file decides where it lands, and **`docs`** is the markdown shown after install. Put every manual step in `docs` — module registration, migrations, middleware, codegen. It's the only instruction the installer sees.
+  </Step>
+  <Step title="Build the registry">
+    ```bash
+    bunx @mercurjs/cli@rc build
+    ```
+
+    This reads `registry.json`, resolves each block's imports, embeds file contents, and writes one JSON per block into `r/` — `r/announcements.json`, plus an index `r/registry.json`.
+  </Step>
+  <Step title="Host it">
+    Serve the `r/` directory from any static host (GitHub Pages, Vercel, S3 — anything that makes `{name}.json` publicly reachable).
+  </Step>
+  <Step title="Install it into a project">
+    In a consumer project, register your registry in `blocks.json` and install:
+
+    ```json blocks.json
+    {
+      "registries": {
+        "@my-org": "https://my-registry.example.com/r/{name}.json"
+      }
+    }
+    ```
+
+    ```bash
+    bunx @mercurjs/cli@rc add @my-org/announcements
+    ```
+
+    The CLI fetches the JSON, maps each file's `type` to the consumer's aliases, rewrites imports, and prints your `docs` instructions.
+  </Step>
+</Steps>
+
+## Verify
+
+1. `r/announcements.json` exists after the build and embeds every file's content.
+2. In the consumer project, the files landed under the alias-mapped paths and imports resolve.
+3. After following your own `docs` steps (module registration, migrations, codegen), `bun run build` passes and the vendor portal shows the Announcements page.
+4. `bunx @mercurjs/cli@rc diff @my-org/announcements` reports no changes — the installed copy matches the registry.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="How do I depend on another block or an npm package?">
+    Other blocks go in `registryDependencies` (e.g. `@my-org/reviews`) — the CLI installs them in order automatically. NPM packages go in `dependencies`; the build also auto-detects them from your imports, so you rarely list transitive ones by hand.
+  </Accordion>
+  <Accordion title="Can I make the registry private?">
+    Yes — use the object form with headers in the consumer's `blocks.json`: `{ "url": "…/{name}.json", "headers": { "Authorization": "Bearer ${REGISTRY_TOKEN}" } }`. The env var is resolved from the installer's environment. See [Registry](/rc/learn/registry).
+  </Accordion>
+  <Accordion title="How do consumers get updates to my block?">
+    They run `mercurjs diff <block>` to compare their local copy against your registry, then `add --overwrite` to take the new version. Because blocks are source, consumers with local edits merge deliberately rather than being force-upgraded.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Registry" href="/rc/learn/registry">
+    The full registry.json schema, auth, and block dependencies.
+  </Card>
+  <Card title="Blocks" href="/rc/learn/blocks">
+    What blocks can contain and how consumers manage them.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/configure-commissions.mdx

@@ -0,0 +1,127 @@
+---
+title: "Configure commissions"
+description: "Set the global commission, add scoped rules for categories and sellers, and confirm the right rate lands on an order."
+---
+
+Commissions are how your marketplace earns. Mercur matches a **commission rate** to every order line item through rules, with one **global commission** as the catch-all. In this tutorial you'll set up a realistic three-tier configuration and verify which rate wins on a real order.
+
+<Info>
+  **The most specific rate wins.** Rules combine with AND across dimensions and OR within a dimension, and among matching rates the one scoping the most dimensions applies. You never order rates by priority — specificity is the priority. The full algorithm is in [Commission](/rc/learn/commissions).
+</Info>
+
+## What you'll build
+
+- A global commission of 15% that also commissions shipping.
+- A 12% rate for the Electronics category.
+- An 8% rate for Electronics sold by one specific premium seller.
+
+An electronics order from the premium seller should produce commission lines at 8% — not 12%, not 15%.
+
+## Set up the rates
+
+<Steps>
+  <Step title="Set the global commission">
+    Every marketplace needs exactly one default rate — the fallback when nothing more specific matches. Create it with `is_default`:
+
+    ```bash
+    curl -X POST http://localhost:9000/admin/commission-rates \
+      -H "Authorization: Bearer <admin-token>" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "name": "Global Commission",
+        "code": "global",
+        "type": "percentage",
+        "value": 15,
+        "is_default": true,
+        "include_shipping": true
+      }'
+    ```
+
+    <Note>
+      `include_shipping` only has an effect on the global commission — shipping methods are always commissioned from the global rate, never from scoped rates. In the Admin Panel this lives on the Global Commission card under **Settings → Commissions**.
+    </Note>
+  </Step>
+  <Step title="Add a category-scoped rate">
+    A rate becomes scoped by attaching **rules**. Each rule names a dimension (`reference`) and a value (`reference_id`):
+
+    ```bash
+    curl -X POST http://localhost:9000/admin/commission-rates \
+      -H "Authorization: Bearer <admin-token>" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "name": "Electronics Commission",
+        "code": "electronics",
+        "type": "percentage",
+        "value": 12,
+        "rules": [
+          { "reference": "product_category", "reference_id": "pcat_electronics" }
+        ]
+      }'
+    ```
+
+    Available dimensions: `product`, `product_type`, `product_collection`, `product_category`, and `seller`.
+  </Step>
+  <Step title="Add a two-dimension rate for the premium seller">
+    Combining a `seller` rule with a `product_category` rule means *both* must match — this rate applies only to that seller's electronics:
+
+    ```bash
+    curl -X POST http://localhost:9000/admin/commission-rates \
+      -H "Authorization: Bearer <admin-token>" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "name": "Premium seller electronics",
+        "code": "premium-electronics",
+        "type": "percentage",
+        "value": 8,
+        "rules": [
+          { "reference": "seller", "reference_id": "slr_premium" },
+          { "reference": "product_category", "reference_id": "pcat_electronics" }
+        ]
+      }'
+    ```
+
+    Because it scopes two dimensions, it beats the one-dimension Electronics rate whenever both match — regardless of which rate was created first.
+  </Step>
+  <Step title="Place a test order">
+    Commission lines are calculated when an order is placed — rates are never applied retroactively. Place an order containing an electronics item from the premium seller (via your storefront or the Store API), then inspect the order's commission lines.
+  </Step>
+</Steps>
+
+## Verify
+
+1. List the rates and confirm all three exist and are enabled:
+   ```bash
+   curl http://localhost:9000/admin/commission-rates \
+     -H "Authorization: Bearer <admin-token>"
+   ```
+2. On the placed order, each electronics line item from the premium seller has a commission line with `code: "premium-electronics"` and `rate: 8`.
+3. The order's shipping method has a commission line from the **global** rate (because `include_shipping` is on).
+4. Change a rate now and confirm the existing order's commission lines are untouched — `CommissionLine` records are a permanent audit trail.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="How do I charge a flat fee instead of a percentage?">
+    Use `"type": "fixed"` with per-currency `values`: `[{ "currency_code": "usd", "amount": 2 }, { "currency_code": "eur", "amount": 1.8 }]`. The scalar `value` is the fallback for currencies without an entry.
+  </Accordion>
+  <Accordion title="What happens when two rates tie on specificity?">
+    Ties break deterministically to the **oldest rate**. But if you find yourself relying on tie-breaking, prefer making one rate more specific — it reads better in the Admin Panel and survives audits.
+  </Accordion>
+  <Accordion title="Do rate changes affect existing orders?">
+    No. Commission is snapshotted into `CommissionLine` records at order placement. Changing or disabling a rate only affects future orders — the lines on past orders are a permanent audit trail that payouts read from.
+  </Accordion>
+  <Accordion title="Can a rate match multiple values in one dimension?">
+    Yes — rules within the same dimension are OR'd. A rate with two `product_category` rules matches items in either category, and still counts as one dimension for specificity.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Commission" href="/rc/learn/commissions">
+    The full matching algorithm, calculation pipeline, and data model.
+  </Card>
+  <Card title="Set up seller payouts" href="/rc/resources/tutorials/seller-payouts-stripe">
+    Where commission is deducted — the settlement side of the marketplace.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/custom-api-route.mdx

@@ -0,0 +1,142 @@
+---
+title: "Add a custom API route"
+description: "Create a backend endpoint, regenerate the route map, and call it from a panel page with full type safety end to end."
+---
+
+Mercur's typed API client isn't hand-maintained — its types are **generated from your actual route files**. That means a custom endpoint you add to the API package becomes a first-class, fully typed client call after one codegen run. This tutorial walks the whole loop: route → codegen → typed call from a custom panel page.
+
+<Info>
+  **The contract is generated, not declared.** You never write an interface for your endpoint. `mercurjs codegen` reads the route's handler and validators and emits the `Routes` type the client consumes — so the panel call site breaks at compile time the moment the backend changes. This loop is also what makes Mercur projects reliable targets for AI agents: see [Building with AI](/rc/resources/ai/overview).
+</Info>
+
+## What you'll build
+
+A `GET /vendor/sales-summary` endpoint returning the seller's order count, called from a custom vendor portal page via `client.vendor.salesSummary.query()` with inferred types.
+
+## Build the loop
+
+<Steps>
+  <Step title="Create the route">
+    API routes follow Medusa's file conventions inside your API package. The URL path mirrors the directory path:
+
+    ```typescript packages/api/src/api/vendor/sales-summary/route.ts
+    import { AuthenticatedMedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+    export async function GET(
+      req: AuthenticatedMedusaRequest,
+      res: MedusaResponse
+    ) {
+      const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+      const { data: orders } = await query.graph({
+        entity: "order",
+        fields: ["id"],
+        filters: { seller_id: req.auth_context.actor_id },
+      })
+
+      res.json({ order_count: orders.length })
+    }
+    ```
+
+    Routes under `src/api/vendor/*` run behind the vendor authentication middleware, so `req.auth_context` identifies the calling seller. Use `src/api/admin/*` for operator endpoints and `src/api/store/*` for public storefront endpoints.
+  </Step>
+  <Step title="Regenerate the route map">
+    ```bash
+    bunx @mercurjs/cli@rc codegen
+    ```
+
+    Codegen scans your route files and rewrites the generated `Routes` type that your panel apps already import:
+
+    ```typescript apps/vendor/src/lib/client.ts
+    import { createClient, type InferClient } from "@mercurjs/client"
+    import type { Routes } from "@acme/api/_generated"
+
+    declare const __BACKEND_URL__: string
+
+    export const client: InferClient<Routes> = createClient({
+      baseUrl: __BACKEND_URL__,
+      fetchOptions: { credentials: "include" },
+    })
+    ```
+
+    This file ships with the starter template — you don't need to touch it. After codegen, `client.vendor.salesSummary` simply exists, typed.
+
+    <Tip>
+      Run `bunx @mercurjs/cli@rc codegen --watch` during development so the route map regenerates as you edit route files.
+    </Tip>
+  </Step>
+  <Step title="Call it from a panel page">
+    Drop a page into the vendor app and call the endpoint through the client. Route segments map to camelCase properties, and the HTTP method is chosen by the terminal call: `query` (GET), `mutate` (POST), `delete` (DELETE).
+
+    ```tsx apps/vendor/src/routes/sales-summary/page.tsx
+    import { useQuery } from "@tanstack/react-query"
+    import { Container, Heading, Text } from "@medusajs/ui"
+    import { ChartBar } from "@medusajs/icons"
+    import type { RouteConfig } from "@mercurjs/dashboard-sdk"
+    import type { InferClientOutput } from "@mercurjs/client"
+    import { client } from "../../lib/client"
+
+    export const config: RouteConfig = {
+      label: "Sales summary",
+      icon: ChartBar,
+    }
+
+    type Summary = InferClientOutput<typeof client.vendor.salesSummary.query>
+
+    export default function SalesSummaryPage() {
+      const { data } = useQuery<Summary>({
+        queryKey: ["sales-summary"],
+        queryFn: () => client.vendor.salesSummary.query(),
+      })
+
+      return (
+        <Container className="divide-y p-0">
+          <div className="flex items-center justify-between px-6 py-4">
+            <Heading>Sales summary</Heading>
+          </div>
+          <div className="px-6 py-4">
+            <Text size="small" className="text-ui-fg-subtle">
+              Orders: {data?.order_count ?? "—"}
+            </Text>
+          </div>
+        </Container>
+      )
+    }
+    ```
+
+    `InferClientOutput` extracts the response type straight from the client method — change the route's response shape, rerun codegen, and this component stops compiling until you update it.
+  </Step>
+</Steps>
+
+## Verify
+
+1. Start the project (`bun run dev`) and log into the vendor portal.
+2. **Sales summary** appears in the sidebar (the `config` export registered it); the page shows the order count.
+3. `curl http://localhost:9000/vendor/sales-summary` without a token returns an authentication error — the vendor middleware guards your route.
+4. Change the route to return `{ count: ... }` instead of `{ order_count: ... }`, rerun codegen, and confirm the page fails to type-check — that's the generated contract doing its job. Revert after.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="How do path parameters work in the client?">
+    Use `$`-prefixed segments: a route at `src/api/vendor/things/[id]/route.ts` is called as `client.vendor.things.$id.query({ $id: "thing_123" })`. The `$id` key is threaded into the URL path; everything else in the object becomes query params (GET) or the JSON body (POST).
+  </Accordion>
+  <Accordion title="How do I handle errors from the client?">
+    Failed requests throw `ClientError` from `@mercurjs/client`, carrying `status`, `statusText`, and the backend's `message`. Wrap calls in try/catch or let TanStack Query surface the error. Full reference: [API Client](/rc/tools/api-client).
+  </Accordion>
+  <Accordion title="Where do request validation schemas go?">
+    Follow Medusa conventions: a `validators.ts` next to the route with a Zod schema, wired through the route's middleware. Codegen reads validators too, so the client's input type reflects them.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="API Client" href="/rc/tools/api-client">
+    Everything the typed client can do — inputs, outputs, errors, React Query.
+  </Card>
+  <Card title="Extend a workflow" href="/rc/resources/customization/extend-a-workflow">
+    Put multi-step business logic behind your endpoint with rollback support.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/custom-panel-page.mdx

@@ -0,0 +1,78 @@
+---
+title: "Add a custom panel page"
+description: "Add a page to the vendor portal with file-based routing — the dashboard SDK wires it in automatically."
+---
+
+Adding a page to the admin panel or vendor portal takes one file. The dashboard SDK scans `src/routes/` at build time, registers the route, and — if you export a `config` — adds it to the sidebar with a label and icon. No route table, no registration call.
+
+<Info>
+  **Adding vs changing.** This tutorial *adds* a brand-new page — the right move for new features. To *change* an existing page, don't rebuild it: drop a route at the same path and [re-compose the built-in page's slots](/rc/resources/tutorials/recompose-a-page). The [decision guide](/rc/resources/customization/extending-panels#choosing-your-extension-mechanism) compares every extension mechanism.
+</Info>
+
+## What you'll build
+
+A `/reviews` page in the vendor portal with a sidebar entry — from a single file.
+
+## Add the page
+
+<Steps>
+  <Step title="Create the route file">
+    Drop a `page.tsx` under `src/routes/` in your vendor app. The file path becomes the URL, and the default export is the page:
+
+    ```tsx apps/vendor/src/routes/reviews/page.tsx
+    import { Container, Heading } from "@medusajs/ui"
+    import { Star } from "@medusajs/icons"
+    import type { RouteConfig } from "@mercurjs/dashboard-sdk"
+
+    export const config: RouteConfig = {
+      label: "Reviews",
+      icon: Star,
+      rank: 10,
+    }
+
+    export default function ReviewsPage() {
+      return (
+        <Container className="divide-y p-0">
+          <div className="flex items-center justify-between px-6 py-4">
+            <Heading>Reviews</Heading>
+          </div>
+        </Container>
+      )
+    }
+    ```
+  </Step>
+  <Step title="Let the SDK wire it up">
+    At build time the SDK registers the `/reviews` route, generates the sidebar item from `config` (`label`, `icon`, `rank`), and hot-reloads the route tree when you add or remove page files. Dynamic segments use brackets — `src/routes/reviews/[id]/page.tsx` becomes `/reviews/:id`. The full path-to-route table is in [Extending Panels](/rc/resources/customization/extending-panels#routing-conventions).
+  </Step>
+  <Step title="Open it in the running panel">
+    Start the project (`bun run dev`) and open the vendor portal — **Reviews** appears in the sidebar at the position set by `rank`, and `/reviews` renders your component.
+  </Step>
+</Steps>
+
+## Verify
+
+1. The sidebar shows **Reviews** with the star icon.
+2. Navigating to `/reviews` renders the page inside the standard panel layout (sidebar and topbar intact).
+3. Removing the `config` export keeps the route working but drops the sidebar item.
+4. Deleting the file removes the route entirely.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="How do I fetch data on my page?">
+    Use the [typed API client](/rc/tools/api-client) with TanStack Query — the panels already ship both. For a full loop including a custom backend endpoint, follow [Add a custom API route](/rc/resources/tutorials/custom-api-route).
+  </Accordion>
+  <Accordion title="Can the page live under /settings?">
+    Yes — place the file under a `settings/` route segment and set `nested: "/settings"` in the config to group its sidebar item under Settings.
+  </Accordion>
+  <Accordion title="Does the same work for the admin panel?">
+    Identically — drop the file in the admin app's `src/routes/` instead. Both panels use the same SDK and conventions.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page" />
+  <Card title="Add a custom API route" href="/rc/resources/tutorials/custom-api-route" />
+</CardGroup>

package/content/resources/tutorials/first-marketplace.mdx

@@ -0,0 +1,45 @@
+---
+title: "Build your first marketplace"
+description: "Go end-to-end: create a project, approve a seller, list a product, place a split order, and watch a payout settle."
+---
+
+<Note>
+  This tutorial is being written. The outline below is the intended structure.
+</Note>
+
+<Info>
+  **One order, three perspectives.** The same purchase looks different on every surface: the customer sees one checkout, the operator sees an order group with per-seller child orders, and each seller sees only their slice. Keeping those three views straight is the core mental model of a Mercur marketplace — this tutorial walks all three.
+</Info>
+
+## What you'll build
+
+A working marketplace with one approved seller, one product, and one split order that settles into a payout. Prerequisites listed up front.
+
+<Steps>
+  <Step title="Create the project">
+    Condensed link back to [Installation](/rc/learn/installation).
+  </Step>
+  <Step title="Approve a seller">
+    From the Admin Panel.
+  </Step>
+  <Step title="List a product">
+    From the Vendor Panel.
+  </Step>
+  <Step title="Place a split order">
+    From the storefront or Store API.
+  </Step>
+  <Step title="See the payout">
+    From the Vendor Panel.
+  </Step>
+</Steps>
+
+## Verify
+
+A checklist of what "done" looks like — the observable end state to confirm every step worked.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a feature with a block" href="/rc/resources/tutorials/add-a-block" />
+  <Card title="Configure commissions" href="/rc/resources/tutorials/configure-commissions" />
+</CardGroup>

package/content/resources/tutorials/handle-product-requests.mdx

@@ -0,0 +1,80 @@
+---
+title: "Handle product requests"
+description: "Walk a vendor's product submission and a follow-up edit through the operator review pipeline — confirm, decline, or send back."
+---
+
+Because Mercur's catalog is [shared](/rc/learn/products), vendors never mutate products directly. New products and edits arrive as **product changes** — reviewable requests the operator confirms, declines, or sends back for revision. This tutorial plays both roles: the vendor submitting, and the operator reviewing.
+
+<Info>
+  **Nothing touches the live product while a change is pending.** A `ProductChange` bundles ordered actions (`UPDATE`, `VARIANT_ADD`, `ATTRIBUTE_UPDATE`, …) that are applied only on confirmation. Declining or canceling leaves the product exactly as it was — and confirmed changes are never deleted, so the same records double as the product's audit trail.
+</Info>
+
+## What you'll build
+
+One complete review cycle: a vendor submits a new product, the operator requests a revision, the vendor resubmits, the operator publishes. Then a smaller edit request on the now-live product.
+
+## Review outcomes
+
+The review queue on the admin product detail offers three outcomes:
+
+| Action | Effect |
+|--------|--------|
+| **Confirm** | The product is published into the shared catalog |
+| **Reject** | Status becomes `rejected`; the product stays out of the catalog |
+| **Request changes** | The submission returns to the vendor with a reason (`requires_action_by` / `requires_action_reason`) |
+
+## Run the review cycle
+
+<Steps>
+  <Step title="Submit a product as the vendor">
+    In the Vendor Portal, create a product. Vendor-created products enter the catalog with status **`proposed`** — visible only to their creator, not to other sellers or the storefront.
+
+    Behind the scenes the platform records a `ProductChange` with a `PRODUCT_ADD` action and `created_by` set to the submitting member. That attribution is what keeps the seller's unpublished submissions in their own product list.
+  </Step>
+  <Step title="Request changes as the operator">
+    In the Admin Panel, open the product and choose **Request changes** with a note — say, "add product dimensions". Use the external note for the vendor-visible message; internal notes stay operator-only.
+  </Step>
+  <Step title="Revise and resubmit as the vendor">
+    Back in the Vendor Portal, the product page shows the revision request and the operator's note. The vendor updates the product and resubmits. As the operator, **Confirm** this time — the product's status flips to `published` and it enters the shared catalog for every eligible seller.
+  </Step>
+  <Step title="Request an edit on the live product">
+    Now that the product is published, edits also flow through review. As the vendor, change the product's description. This creates a new `ProductChange` in `pending` with an `UPDATE` action — the live product is unchanged until the operator confirms. Confirm it and watch the description update.
+  </Step>
+</Steps>
+
+<Note>
+  Any seller may propose changes to any published product — the shared catalog is collaborative. Selling-eligibility restrictions limit who may *sell* a product, not who may *suggest improvements* to it.
+</Note>
+
+## Verify
+
+1. After step 1, the product is `proposed`: visible in the submitting vendor's list, absent from other vendors' lists and the Store API.
+2. After **Request changes**, the vendor sees the revision note; the change is flagged `requires action`.
+3. After the final **Confirm** in step 3, the product is `published` and appears in the Store API.
+4. During step 4, the storefront still shows the old description while the change is `pending` — and the new one after confirmation.
+5. The product's change history lists every change with who requested it, who reviewed it, and when.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Do all edits require operator review?">
+    No — some low-risk edits are **auto-confirmed**: they still create a change record for the audit trail but apply immediately without waiting. Structural changes (variants, attributes, status) go through review.
+  </Accordion>
+  <Accordion title="Can the vendor withdraw a pending request?">
+    Yes — a pending change can be **canceled** by its requester, recorded with the same audit fields (`canceled_by`, timestamp). Once confirmed or declined, the outcome is final; a new change is needed for further edits.
+  </Accordion>
+  <Accordion title="What's the difference between rejecting and requesting changes?">
+    **Reject** is terminal for a submission — the product is marked `rejected` and stays out of the catalog. **Request changes** keeps the change alive and hands it back to the vendor with a reason; it's the "revise and resubmit" path.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Product Requests & Approvals" href="/rc/learn/product-requests">
+    The full ProductChange data model, actions, and lifecycle.
+  </Card>
+  <Card title="Master products & offers" href="/rc/resources/tutorials/master-products-and-offers">
+    What happens after publication — sellers listing against the shared record.
+  </Card>
+</CardGroup>