The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
docs: split use cases into standalone marketplace and marketplace inside a store (#1705)
Viktor Holik190ab984ea85
diff --git a/apps/docs/docs.json b/apps/docs/docs.jsonindex f8729edd1..ecd5de403 100644--- a/apps/docs/docs.json+++ b/apps/docs/docs.json@@ -41,7 +41,6 @@"home","learn/introduction","learn/why-mercur",- "learn/use-cases",{"group": "Build with AI","pages": [@@ -54,6 +53,14 @@"learn/migration-to-2-0"]},+ {+ "group": "Use cases",+ "icon": "signs-post",+ "pages": [+ "learn/use-cases/standalone-marketplace",+ "learn/use-cases/marketplace-inside-store"+ ]+ },{"group": "Legal","icon": "scale-balanced",@@ -419,7 +426,7 @@"pages": ["resources/integrations/overview","resources/integrations/stripe-connect",- "resources/integrations/magento2"+ "resources/integrations/magento2"]},{@@ -1473,6 +1480,10 @@{"source": "/resources/tutorials/replace-panel-components","destination": "/resources/customization/extending-panels"+ },+ {+ "source": "/learn/use-cases",+ "destination": "/learn/use-cases/standalone-marketplace"}],"footer": {diff --git a/apps/docs/learn/use-cases.mdx b/apps/docs/learn/use-cases.mdxdeleted file mode 100644index 828839265..000000000--- a/apps/docs/learn/use-cases.mdx+++ /dev/null@@ -1,70 +0,0 @@-----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>diff --git a/apps/docs/learn/use-cases/marketplace-inside-store.mdx b/apps/docs/learn/use-cases/marketplace-inside-store.mdxnew file mode 100644index 000000000..fea5939c7--- /dev/null+++ b/apps/docs/learn/use-cases/marketplace-inside-store.mdx@@ -0,0 +1,65 @@+---+title: "Add a marketplace to your store"+sidebarTitle: "Marketplace inside a store"+description: "Sell third-party seller offers next to your own products in a store you already run, such as Magento 2. Your store keeps the storefront, cart, checkout and payment; Mercur runs the sellers, their offers, one order per seller, commissions and payouts."+---++You already sell your own products on a platform such as Magento 2 or Adobe Commerce, and you want third-party sellers on the same product page and in the same checkout, without moving your catalog or your payments. Your store stays the storefront. Mercur becomes the marketplace layer behind it: sellers log into the vendor panel to list offers against your products and ship their orders, and a connector keeps the two systems in step.++<Card title="Magento 2 integration" icon="store" href="/resources/integrations/magento2">+ Install the Mercur plugin and the Magento connector, connect the two stores, run the first sync and place a mixed first-party and seller order.+</Card>++<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." />++## Use cases++<CardGroup cols={2}>+ <Card title="Sell seller offers next to your stock" icon="store" href="/resources/integrations/magento2">+ Seller offers appear in a buy box on your product page; your own stock stays one of the candidates and sells exactly as before.+ </Card>+ <Card title="Let sellers compete on your SKUs" icon="tags" href="/platform/offer/overview">+ Push your catalog to Mercur so sellers can offer on it, and match their offers to your products by SKU or EAN.+ </Card>+ <Card title="Keep checkout and payment where they are" icon="cart-shopping" href="/resources/integrations/magento2#how-a-mixed-order-flows">+ The shopper pays once in your store. Seller lines are mirrored into Mercur and captured only after your invoice is paid.+ </Card>+ <Card title="Split per seller, commission and pay out" icon="money-bill-transfer" href="/platform/order-group/overview">+ Each order becomes one Mercur order per seller with its commission lines; sellers ship from the vendor panel and are paid out by Mercur.+ </Card>+</CardGroup>++## What is a marketplace inside a store?++A hybrid marketplace is a first-party store that also sells other sellers' stock. The operator keeps selling their own products with their own prices, warehouses and carriers; sellers compete on the same products with their own offers. The shopper never notices a second system: one product page, one cart, one payment. Only fulfillment is split, because each seller ships what they sold.++## Why keep your store++A store that is live has a storefront, a theme, integrations, a payment provider, carriers and an order history that nobody wants to migrate. Replacing it to add sellers trades a working system for a project. Keeping it means the marketplace is an addition: your catalog, checkout and payments are untouched, and Mercur only takes the parts a single-store platform does not have — seller accounts and teams, offers, order splitting, commissions and payouts.++## How Mercur does it++| 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 | | ✔ |++The integration has two halves. A plugin on the Mercur API, [`@mercurjs/magento2-connector-plugin`](/resources/integrations/magento2), adds outbound webhooks, an external payment provider and the admin routes the connector needs. A Composer package of Magento modules, [`mercurjs/magento2-connector`](https://github.com/mercurjs/magento2-connector), does the rest:++- **Mercur → your store:** sellers, their offers with prices per website and stock, and published seller products imported as configurable products with images. Webhooks trigger a delta sync; cron is the floor.+- **Your store → Mercur:** your attribute and category taxonomy, optionally your own products so sellers can offer on them, and every order with seller lines once it reaches a configured status.+- **Orders:** the order is placed in your store first, created in Mercur with the payment authorized, captured when the invoice is paid, and shipped by each seller from the [vendor panel](/user-guide/vendor/orders/overview). Seller shipments come back as shipments with tracking; refunds and cancellations flow both ways.++Sellers use the same vendor panel and the same [Offer](/platform/offer/overview), [Order Group](/platform/order-group/overview), [Commission](/platform/commission/overview) and [Payout](/platform/payout/overview) modules as a standalone marketplace. Magento 2 is the storefront platform supported today; the same split applies to any platform that can mirror offers and call the Store API during checkout.++<CardGroup cols={2}>+ <Card title="Magento 2 integration" icon="store" href="/resources/integrations/magento2">+ The setup guide: plugin, connector, configuration, first sync.+ </Card>+ <Card title="Standalone marketplace" icon="arrow-right-arrow-left" href="/learn/use-cases/standalone-marketplace">+ No store yet? Run the whole marketplace on Mercur instead.+ </Card>+</CardGroup>diff --git a/apps/docs/learn/use-cases/standalone-marketplace.mdx b/apps/docs/learn/use-cases/standalone-marketplace.mdxnew file mode 100644index 000000000..3b850883e--- /dev/null+++ b/apps/docs/learn/use-cases/standalone-marketplace.mdx@@ -0,0 +1,64 @@+---+title: "Run a standalone marketplace"+sidebarTitle: "Standalone marketplace"+description: "Launch a multi-vendor marketplace on Mercur: its own storefront, an operator admin, a vendor panel for sellers, and a backend that splits every checkout into one order per seller, computes commissions and pays sellers out."+---++Mercur runs the whole marketplace. Shoppers buy on a storefront built on the Store API, operators approve sellers and review catalog changes in the admin panel, sellers manage offers, orders and payouts in the vendor panel, and the backend turns one checkout into one order per seller. There is no other commerce system in the picture: products, pricing, carts, orders and payments run on Medusa underneath Mercur.++<Card title="Install Mercur" icon="rocket" href="/learn/introduction">+ Create a marketplace project with `create-mercur-app`, seed it and run the API, admin and vendor panel locally.+</Card>++<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." />++## Use cases++<CardGroup cols={2}>+ <Card title="Launch a multi-vendor marketplace" icon="store" href="/platform/store/overview">+ Register sellers, approve or suspend them, and give each a team with roles that never leak into another store.+ </Card>+ <Card title="Curate one shared catalog" icon="book-open" href="/platform/catalog/overview">+ Keep master products in a single catalog, allowlist which sellers may sell which products, and review every submission and edit before it goes live.+ </Card>+ <Card title="Let sellers compete on the same products" icon="tags" href="/platform/offer/overview">+ Sellers list offers against master products with their own SKU, price, stock and shipping; shoppers pick the offer, not a duplicate product.+ </Card>+ <Card title="Split checkout, commission and pay out" icon="money-bill-transfer" href="/platform/order-group/overview">+ One payment becomes one order per seller, commission lines are computed per order, and payouts reach each seller's connected account on a schedule.+ </Card>+</CardGroup>++## What is a standalone marketplace?++A standalone marketplace is a store whose catalog is sold by many sellers rather than by the operator. The operator owns the brand, the storefront and the rules: who may sell, what the catalog looks like, what commission applies. Sellers own their stock, their prices and their fulfillment. The shopper sees one store and pays once; behind it, each seller receives and ships their own part of the order.++## Why run it on Mercur++Building that on a single-store engine means writing the seller layer yourself: seller accounts and teams, a catalog that is shared rather than owned, a review pipeline for edits, order splitting, commission arithmetic, payouts. Mercur ships those as modules on top of Medusa, so the commerce core is mature from day one and the marketplace layer is yours to extend. You self-host it, you own the source of every block you install, and there is no commission on gross merchandise value.++## How Mercur does it++| Surface | Who uses it | Package |+| --- | --- | --- |+| Storefront | Shoppers | Any framework on the [Store API](/references/api/store), or the starter storefront |+| Admin panel | Operators | `@mercurjs/admin` |+| Vendor panel | Sellers | `@mercurjs/vendor` |+| Backend | Everyone | `@mercurjs/core` as a plugin on Medusa |++- **Sellers and teams:** the [Store](/platform/store/overview) module holds seller accounts, their lifecycle (`pending_approval` → `open` → `suspended` / `terminated`) and members with per-store roles.+- **Catalog:** [master products](/platform/catalog/overview) live in one shared catalog; a product–seller link allowlists who may sell them, and every edit flows through the [product change pipeline](/platform/product-edit/overview) with an audit trail.+- **Offers:** an [offer](/platform/offer/overview) is how a seller sells a master product, with offer-scoped price, inventory and shipping profile.+- **Orders and money:** the [Order Group](/platform/order-group/overview) module splits a cart into one order per seller, the [Commission](/platform/commission/overview) module writes commission lines per order, and the [Payout](/platform/payout/overview) module transfers seller earnings through a provider such as Stripe Connect.++Everything is extended the Medusa way: custom modules, workflow hooks, subscribers, extra API routes, and pages dropped into the admin or vendor panel through the [Dashboard SDK](/resources/customization/extending-panels).++<CardGroup cols={2}>+ <Card title="Architecture" icon="sitemap" href="/learn/architecture">+ How the panels, the API and the modules fit together.+ </Card>+ <Card title="Marketplace inside a store" icon="arrow-right-arrow-left" href="/learn/use-cases/marketplace-inside-store">+ Already running a store such as Magento? Keep it and add sellers to it instead.+ </Card>+</CardGroup>