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

package/content/learn/introduction.mdx

@@ -18,11 +18,19 @@ Mercur focuses on the marketplace domain on top.
 
 ## Requirements
 
-- [Node.js v20+](https://nodejs.org/en/download) (LTS)
+- [Node.js v24.22.1+](https://nodejs.org/en/download) (LTS, recommended) or v22.23.4+
 - [Bun v1.3+](https://bun.sh) (recommended package manager)
 - [Git](https://git-scm.com/downloads)
 - PostgreSQL v14+
 
+<Warning>
+  The [October 2026 Node.js security releases](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases)
+  fix several high-severity vulnerabilities, including a remote code execution
+  bug in the Brotli decoder and TLS certificate hostname bypasses. We recommend
+  running Mercur on **Node.js v24.22.1** or later. If you stay on Node.js 22,
+  use v22.23.4 or later.
+</Warning>
+
 <Tip>
   The quickest way to run PostgreSQL locally is with Docker:
 

package/content/learn/use-cases.mdx

@@ -0,0 +1,70 @@
+---
+title: "Use cases"
+sidebarTitle: "Use cases"
+description: "Two ways to run Mercur: as the whole marketplace, with its own storefront, admin and vendor panels, or as the marketplace layer inside a store you already run, selling seller offers next to your own products."
+---
+
+Mercur fits two kinds of business. Pick the one that matches yours; the modules underneath are the same.
+
+<Tabs>
+  <Tab title="Marketplace platform">
+    You are building a marketplace from scratch, or replacing one. Mercur runs everything: the storefront, the operator admin, the vendor panel sellers log into, and the backend that splits every checkout into one order per seller, computes commissions and pays sellers out.
+
+    <img className="block dark:hidden" src="/images/figures/use-case-platform-light.svg" alt="Three Mercur surfaces stacked back to front: the admin Sellers list, the vendor panel's Offers table for ACME, and the storefront product page for the Linen shirt listing the offers a shopper can buy." />
+    <img className="hidden dark:block" src="/images/figures/use-case-platform-dark.svg" alt="Three Mercur surfaces stacked back to front: the admin Sellers list, the vendor panel's Offers table for ACME, and the storefront product page for the Linen shirt listing the offers a shopper can buy." />
+
+    **Pick this when**
+
+    - You don't have a store yet, or you want the marketplace to be the product
+    - Sellers should get their own panel: offers, orders, fulfillment, payouts
+    - You want one shared catalog that every seller lists against
+
+    **What you get**
+
+    | Surface | Who uses it | Package |
+    | --- | --- | --- |
+    | Storefront | Shoppers | Any framework on the Store API, or the starter storefront |
+    | Admin panel | Operators | `@mercurjs/admin` |
+    | Vendor panel | Sellers | `@mercurjs/vendor` |
+    | Backend | Everyone | `@mercurjs/core` on Medusa |
+
+    <CardGroup cols={2}>
+      <Card title="Install Mercur" icon="rocket" href="/learn/introduction">
+        Create a marketplace project and run it locally.
+      </Card>
+      <Card title="Architecture" icon="sitemap" href="/learn/architecture">
+        How the panels, the API and the modules fit together.
+      </Card>
+    </CardGroup>
+  </Tab>
+  <Tab title="Marketplace inside your store">
+    You already sell your own products on a platform like Magento. You want third-party sellers next to them, in the same product page and the same checkout, without moving your catalog or your payments. Your store stays the storefront; Mercur becomes the marketplace layer behind it.
+
+    <img className="block dark:hidden" src="/images/figures/use-case-hybrid-light.svg" alt="A product page in your own store lists your warehouse next to two seller offers from ACME and GLOBEX. A wire leads from the seller rows to a Mercur order group with one order per seller; your own line never leaves your store." />
+    <img className="hidden dark:block" src="/images/figures/use-case-hybrid-dark.svg" alt="A product page in your own store lists your warehouse next to two seller offers from ACME and GLOBEX. A wire leads from the seller rows to a Mercur order group with one order per seller; your own line never leaves your store." />
+
+    **Pick this when**
+
+    - Your store, checkout and payment provider are already live and should stay
+    - You sell first-party stock and want sellers to compete on the same SKUs
+    - Sellers need a panel, but shoppers should never notice a second system
+
+    **Who runs what**
+
+    | Concern | Your store | Mercur |
+    | --- | --- | --- |
+    | Catalog, prices, stock of your own products | ✔ | |
+    | Storefront, cart, checkout, payment capture | ✔ | |
+    | Sellers, their offers, their panel | | ✔ |
+    | One order per seller, commissions, payouts | | ✔ |
+
+    <CardGroup cols={2}>
+      <Card title="Magento 2 integration" icon="store" href="/resources/integrations/magento2">
+        Install the connector and run a mixed first-party and seller order.
+      </Card>
+      <Card title="Order Group module" icon="layer-group" href="/platform/order-group/overview">
+        How one checkout becomes one order per seller.
+      </Card>
+    </CardGroup>
+  </Tab>
+</Tabs>

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

@@ -4,7 +4,7 @@ sidebarTitle: "Data models"
 description: "Every field on the Medusa Product module models the shared catalog is built on, and the relations Mercur adds."
 ---
 
-The catalog's data models belong to Medusa's Product module, version 2.21. 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.
+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
 

package/content/references/api/conventions.mdx

@@ -35,6 +35,26 @@ A handful of vendor routes are public by design: seller registration (`POST /ven
 
 Store routes are public. Customer authentication (session or bearer) is **required** for `/store/order-groups` and **optional** for `/store/offers` and `/store/products`, where it enriches the pricing context when present. Public seller routes only return sellers whose status is `open` and who are not inside a scheduled closure window.
 
+### With the client
+
+`@mercurjs/client` carries the credential for you. Pass `auth` once and every request resolves it fresh, so a token stored after login is picked up by the next call:
+
+```typescript
+import { createClient, adminAuth, vendorAuth, apiKeyAuth, publishableKeyAuth } from "@mercurjs/client"
+
+// inside the admin or vendor panel, or a plugin's dashboard code
+const admin = createClient({ baseUrl, auth: adminAuth() })
+const vendor = createClient({ baseUrl, auth: vendorAuth() })
+
+// a server-side integration with a secret API key
+const integration = createClient({ baseUrl, auth: apiKeyAuth(() => process.env.MERCUR_API_KEY) })
+
+// a storefront
+const store = createClient({ baseUrl, auth: publishableKeyAuth(() => publishableKey) })
+```
+
+`adminAuth()` and `vendorAuth()` read the same token stores the panels write on login (`adminTokenStore`, `vendorTokenStore`, `vendorSellerStore`), so dashboard extensions share the user's session without knowing a storage key. `createTokenStore(key)` builds your own store, falling back to memory where `localStorage` is unavailable. A `401` clears the bearer store unless you pass `onUnauthorized`.
+
 ## Pagination
 
 List endpoints use offset pagination with two query parameters:

package/content/resources/integrations/magento2.mdx

@@ -0,0 +1,162 @@
+---
+title: "Magento 2 marketplace integration"
+sidebarTitle: "Magento 2"
+description: "Turn your Magento 2 or Adobe Commerce store into a multi-vendor marketplace with Mercur. Install the connector, sync seller offers, and split each order per seller."
+---
+
+The Magento 2 connector lets a store you already run sell marketplace offers next to its own catalog. Magento keeps the storefront, cart, checkout, payment capture and your first-party products. Mercur keeps sellers, their offers, the split of one checkout into one order per seller, commission lines and payouts.
+
+The integration has two halves:
+
+- **`@mercurjs/magento2-connector-plugin`**, a plugin for your Mercur API that adds outbound webhooks, an external payment provider and a few admin routes
+- **`mercurjs/magento2-connector`**, a Composer package of Magento modules that mirrors sellers and offers into Magento and talks to Mercur during checkout
+
+<Tip>
+  This page is the setup guide. The connector's source, module layout and development workflow live in the [magento2-connector repository](https://github.com/mercurjs/magento2-connector).
+</Tip>
+
+## Quick start
+
+<Steps>
+  <Step title="Install the plugin in Mercur">
+    Add the plugin and register its payment provider in `medusa-config.ts`:
+
+    ```ts
+    module.exports = withMercur({
+      plugins: [
+        { resolve: "@mercurjs/magento2-connector-plugin", options: {} },
+      ],
+      modules: [
+        {
+          resolve: "@medusajs/medusa/payment",
+          options: {
+            providers: [
+              {
+                resolve: "@mercurjs/magento2-connector-plugin/providers/payment-external",
+                id: "external",
+              },
+            ],
+          },
+        },
+      ],
+    })
+    ```
+
+    Run `medusa db:migrate` afterwards. The provider is registered as `pp_external_external`; it records a payment Magento already captured instead of charging anyone.
+
+    Then enable it for the region your Magento website sells in: open the region in the Mercur admin and add **pp_external_external** to its payment providers. The shadow cart cannot complete without it.
+  </Step>
+  <Step title="Install the Magento package">
+    In your Magento root. The package is installed from its Git repository until it is published to Packagist, so add the repository first:
+
+    ```bash
+    composer config repositories.mercur vcs https://github.com/mercurjs/magento2-connector
+    composer require mercurjs/magento2-connector:dev-main
+    bin/magento module:enable Mercur_Core Mercur_Process Mercur_Connector \
+      Mercur_OfferIndexer Mercur_Catalog Mercur_Settlement Mercur_Frontend Mercur_GraphQl
+    # Only on stores that run Multi-Source Inventory:
+    bin/magento module:enable Mercur_Inventory
+    bin/magento setup:upgrade
+    bin/magento setup:di:compile
+    bin/magento cache:flush
+    ```
+  </Step>
+  <Step title="Get API details">
+    You need four values from Mercur:
+
+    - **Admin API key**: create a secret API key under **Settings → API keys**. If your deployment runs a roles module, bind it to a role that holds only the `integrations` permission; without one the key has full admin access, so treat it like an admin password
+    - **Publishable API key**: the publishable key of the sales channel the shadow cart is created in
+    - **Sales channel ID** and **Region ID**: the channel and the region whose prices the Magento website shows, one region per website
+  </Step>
+  <Step title="Connect Magento">
+    In Magento open **Stores → Configuration → Mercur → Marketplace** and enter the API URL and the four values above. Choose a best offer rule: lowest price, your own stock first, or premium sellers first.
+  </Step>
+  <Step title="Register the webhook">
+    In the Mercur admin open **Settings → Magento → Add endpoint**, enter `https://your_shop_domain/mercur/webhook`, keep every event selected, and copy the signing secret. The connector needs the fulfillment, shipment, delivery, return and refund events to keep orders in step. It is shown once. Paste it into the Magento configuration under **Webhooks → Signing secret**.
+  </Step>
+  <Step title="Run the first sync">
+    Push your taxonomy, then mirror everything:
+
+    ```bash
+    bin/magento mercur:sync taxonomy
+    bin/magento mercur:sync full
+    ```
+
+    Cron keeps the mirror current afterwards: sellers every 15 minutes, offers every 5 minutes, published products hourly, a full resync every night. Each run is a process under **Mercur → Processes** in the Magento admin.
+  </Step>
+</Steps>
+
+## How a mixed order flows
+
+A shopper buys one of your own products and one seller offer in the same checkout and pays once:
+
+1. The product page lists every active seller offer next to your own stock, with its price for that website, any price list strike-through, quantity tiers and an estimated delivery date. Adding an offer marks the cart line as a marketplace line priced by the offer and labels it "Sold by" the seller. The same works through REST and GraphQL with `mercur_offer_id`.
+2. The cart and the checkout group the marketplace lines by seller. Magento copies them into a shadow Mercur cart, asks Mercur for each seller's shipping options and lets the shopper pick one per seller; the sum is the "Seller shipping" total. Your own carriers only price your own lines, and a cart of seller lines only gets the "Shipped by the sellers" method.
+3. The shopper pays in Magento. The invoice includes seller shipping.
+4. After the order is placed, Magento records the capture on the external payment provider and completes the Mercur cart. Mercur answers with an order group, one order per seller, and Magento stores those ids on the order and its lines.
+5. Sellers fulfill in the vendor panel. Each shipped fulfillment becomes its own Magento shipment with its tracking numbers, so partial and multi-parcel deliveries show up as they happen. Deliveries, returns and cancellations update the line's marketplace status, shown to the shopper in their account and to you in the admin.
+6. Mercur computes commission lines when the cart completes and pays sellers from the recorded capture.
+
+If Mercur is unreachable at step 4, the Magento order still succeeds and the `order_retry` process completes the Mercur side on its next run.
+
+## Refunds
+
+| Starts in | What happens |
+| --- | --- |
+| Magento | A credit memo on marketplace lines is reported to Mercur per seller order, with seller shipping split by what each seller charged, so commission lines and payout balances follow |
+| Mercur, a seller or operator refund | Mercur sends `order.refund_requested`; Magento creates an adjustment credit memo and refunds the shopper online when the invoice was captured online |
+| Mercur, a canceled seller order | Magento refunds that seller's lines and shipping |
+
+A `refunds` process every 15 minutes picks up any refund whose webhook did not arrive.
+
+## Essential practices
+
+### One region per website
+
+Offer prices are read for the region configured on each Magento website, including Mercur price lists. A store with a US and an EU website needs two Mercur regions and two website-scoped values of **Mercur region ID**, and each website's base currency must match its region's currency.
+
+### Set delivery estimates
+
+Under **Mercur → Marketplace → Delivery estimates** set the order cut-off time, business days and transit days for each website. A Mercur shipping option can carry its own `transit_days_min` and `transit_days_max` in its data.
+
+### Keep the operator's stock as a candidate
+
+Your own product is always one of the ways to buy a SKU. The best offer rule decides whether it wins over a cheaper seller; `operator_first` keeps your stock on top whenever it is in stock.
+
+### Let webhooks drive, keep cron as the floor
+
+Offer, seller and product events enqueue the matching delta sync within a minute. The cron schedules exist so the mirror heals after a missed delivery; a full nightly resync removes anything a delta could not see.
+
+## Your products or seller offers
+
+| Situation | What happens |
+| --- | --- |
+| A product only you sell | A normal Magento line: your price, your stock, your carriers |
+| A product only sellers sell | Imported from Mercur, as a configurable product when its variant axes are Magento attributes; it is in stock while an offer is available and every line is a marketplace line |
+| A product both you and sellers sell | Same SKU, one buy box; the best offer rule picks the default and the shopper can choose another. When you run out, the product stays buyable from sellers |
+
+Each seller has a page at `/seller/{handle}` listing what they sell on your store. In the Magento admin, **Mercur → Sellers** and **Mercur → Offers** show the mirror, orders show each seller order with its status, and the product page lists the offers for that SKU.
+
+## Not supported yet
+
+- Buyer and seller messaging, order incidents and seller ratings
+- Documents sellers attach to orders
+- A third-party tax engine for seller lines; Magento taxes them with the product's tax class
+- Mercur promotions; Magento cart rules still apply to seller lines
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Connector repository" icon="github" href="https://github.com/mercurjs/magento2-connector">
+    Modules, development workflow, and the webhook handler registry.
+  </Card>
+  <Card title="Offer module" icon="tag" href="/platform/offer/overview">
+    How offers carry seller SKU, price, inventory and shipping.
+  </Card>
+  <Card title="Order Group module" icon="layer-group" href="/platform/order-group/overview">
+    How one checkout becomes one order per seller.
+  </Card>
+  <Card title="Commission module" icon="percent" href="/platform/commission/overview">
+    How commission lines are computed at completion.
+  </Card>
+</CardGroup>

package/content/resources/integrations/overview.mdx

@@ -23,6 +23,16 @@ interface.
   </Card>
 </CardGroup>
 
+## Storefront platforms
+
+A storefront you already run can sell marketplace offers next to its own catalog. Mercur keeps sellers, offers, split orders, commissions and payouts; the platform keeps checkout and payment.
+
+<CardGroup cols={2}>
+  <Card title="Magento 2" icon="store" href="/resources/integrations/magento2">
+    Set up the Magento 2 connector.
+  </Card>
+</CardGroup>
+
 ## Blocks
 
 Other integrations ship as installable blocks. You add the block, own its source

package/content/resources/integrations/stripe-connect.mdx

@@ -21,7 +21,7 @@ This guide covers both. It walks through setting up Stripe, configuring both pro
 - A [Stripe account](https://dashboard.stripe.com) with Connect enabled
 - Stripe Secret API key and Publishable API key
 - A running Mercur project ([installation guide](/learn/introduction))
-- Node.js 20+
+- Node.js 22.22+
 
 ## Architecture overview
 

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

@@ -54,14 +54,15 @@ A `GET /vendor/sales-summary` endpoint returns the seller's order count. You cal
     Codegen 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 { createClient, vendorAuth, 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" },
+      fetchOptions: { credentials: "omit" },
+      auth: vendorAuth(),
     })
     ```
 

package/llms.txt

@@ -21,6 +21,7 @@ package (`node_modules/@mercurjs/docs/`).
 - [Registry](content/learn/registry.mdx) — Create, build, and host your own block registry.
 - [Seller Members](content/learn/seller-members.mdx) — Multi-user seller accounts — member data, team management, store switching, and access rules.
 - [Seller](content/learn/sellers.mdx) — The central marketplace actor — seller profile, lifecycle, registration flows, and business rules.
+- [Use cases](content/learn/use-cases.mdx) — Two ways to run Mercur: as the whole marketplace, with its own storefront, admin and vendor panels, or as the marketplace layer inside a store you already run, selling seller offers next to your own products.
 - [Why Mercur](content/learn/why-mercur.mdx) — Why teams choose Mercur to run an enterprise marketplace: governance, ownership, and composability without a closed platform.
 
 ## Resources — tutorials, integrations, deployment
@@ -42,6 +43,7 @@ package (`node_modules/@mercurjs/docs/`).
 - [How to Extend the Panels](content/resources/customization/extending-panels.mdx) — Add pages, widgets, navigation overrides, and form and table fields to the admin and vendor panels without forking.
 - [Medusa Cloud](content/resources/deployment/medusa-cloud.mdx) — Deploy the Mercur backend, admin panel, and vendor panel on Medusa Cloud.
 - [Self-host Mercur](content/resources/deployment/self-host.mdx) — Deploy a Mercur marketplace to your own infrastructure: the API, the panels, and the databases behind them.
+- [Magento 2 marketplace integration](content/resources/integrations/magento2.mdx) — Turn your Magento 2 or Adobe Commerce store into a multi-vendor marketplace with Mercur. Install the connector, sync seller offers, and split each order per seller.
 - [Integrations](content/resources/integrations/overview.mdx) — Extend Mercur with third-party providers and installable blocks.
 - [Stripe Connect](content/resources/integrations/stripe-connect.mdx) — Set up Stripe Connect for marketplace payments and seller payouts, from Stripe Dashboard configuration to the full end-to-end payment lifecycle.
 - [How to Add a Block](content/resources/tutorials/add-a-block.mdx) — Install the reviews block end-to-end and follow it live across the admin, vendor, and storefront surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercurjs/docs",
-  "version": "2.3.8-canary.4",
+  "version": "2.3.9-canary.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/mercurjs/mercur",