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
Product Description -- Mercur.js
What Is This?
Mercur is an open-source, MIT-licensed marketplace platform built on top of the Medusa commerce framework. Medusa supplies the core commerce engine — products, pricing, carts, orders, fulfillment, promotions, payments, events. Mercur adds the marketplace layer on top: sellers, onboarding, commissions, vendor payouts, order splitting, requests, reviews, and three role-specific surfaces (Admin, Vendor, Store).
The product has three audiences:
- Marketplace operators — run the platform via the Admin Panel and Admin API.
- Sellers / vendors — run their store via the Vendor Portal and Vendor API.
- Developers / AI agents — extend the platform via the Dashboard SDK, typed API client, and Medusa's standard module/workflow extension model.
Core Features
Multi-Vendor Sellers
- Seller account creation, approval, suspension, unsuspend, and termination workflows. Account status is one of
pending_approval,open,suspended, orterminated. - Seller profile with name, slug, description, address, professional details, payment details, and metadata.
- Scheduled closures — a seller can set
closed_from/closed_toto temporarily go offline (storefront unavailable, no new orders) without changing account status; the store auto-resumes onceclosed_topasses. - Premium sellers — an operator-only
is_premiumflag used by the storefront for featured placement, badges, and priority curation (vendors cannot self-designate). - Members are many-to-many — multiple members per seller, and one user can belong to multiple sellers and switch between them via a store switcher (fully isolated access per store). Every seller must have at least one admin member; member email is unique within a single seller. Invitations via
invite-seller/accept-member-invite. - Public seller storefronts exposed through the Store API.
Commission Management
- Configurable commission rules and rates: fixed (per-currency amounts, falling back to a default
value) or percentage. - Rules match across five dimensions —
product,product_type,product_collection,product_category,seller. Resolution is most-specific-wins (AND across dimensions, OR within a dimension); ties break to the oldest rate. Only the global rate may commission shipping (include_shipping). - All commission arithmetic uses BigNumber (arbitrary precision) for financial accuracy.
- Bulk batch updates via
batch-commission-rules. - Per-order commission lines generated automatically during checkout (
refresh-order-commission-lines). - Commission visibility for both marketplace operators and individual vendors.
Vendor Payouts
- Single payout provider per marketplace, modelled on Medusa's payment providers: configure exactly one provider on the payout module (the built-in system provider is used when none is configured). Webhooks arrive at
/hooks/payout. Stripe Connect ships in@mercurjs/stripe-connector-plugin; any other provider implementsIPayoutProvider(createAccount,retrieveAccount,createOnboarding,createPayout,reversePayout,getWebhookActionAndData). - Payout account creation and onboarding flows (
create-payout-account,create-onboarding,create-or-refresh-seller-payout-account). Each account carries an onboarding record holding provider-specific data (e.g. Stripe Connect links). - Payout account lifecycle:
PENDING→ACTIVE, thenACTIVE↔RESTRICTED(provider flagged, e.g. missing KYC) orACTIVE→REJECTED, driven by provider webhooks. - One
payoutper seller order (order total minus commission, net of refunds that landed before it) and onepayout_reversalper later refund (net of its commission share), mirroring Medusa'sPayment→Refund. Status:pending,on_hold,processing,paid,failed,aborted.create-order-payoutsputs an order that is not ready (no active account, not fulfilled, payment not captured) on hold and re-decides it on the next call;create-payout-reversalstakes the refunded share back;retry-payoutretries a failed or held payout. - Core ships no payout schedule. When payouts run is the integration's call: the Stripe connector plugin brings the scheduled jobs (onboarding sync, capture validation, payouts, reversals, settlements, failed-operation alerts, KYC monitoring), settlements, operator adjustments and their admin screens.
- Webhook processing for provider events (
process-payout-for-webhook). - Vendor-side onboarding status and payout history in the Vendor Portal.
Order Splitting & Order Groups
- A single customer cart spanning multiple sellers is split into per-seller orders.
- Order Group entity aggregates child orders, payment, and status for the shopper. It exposes a human-readable auto-incrementing
display_idand a read-onlycart_idlink to the originating cart (carts are immutable after checkout).seller_countandtotalare computed at query time, not stored. - Admin gets platform-wide order visibility; vendors see only their slice.
- Independent fulfillment, returns, and refunds per child order.
Master Products & Offers
- Master products form a single shared catalog — products are not seller-owned. Creating a product adds it to the shared catalog; the creator only gets attribution on unreviewed submissions.
- A product–seller link acts as an allowlist controlling which sellers may sell which products.
- Product status lifecycle:
draft→proposed→published, or →rejected. Vendor-created products default toproposed. Visibility: vendors see their own submissions (any status) plus published products not allowlisted to others; admins see everything; the store sees published products of visible sellers. - Offers are how a seller sells against a master product. An offer carries the seller's own SKU (unique per seller), price (offer-scoped pricing rule), inventory (offer-scoped, not variant-scoped), and shipping profile. Cart/order line items record which offer was purchased.
Product Requests & Change Pipeline
- All product edits flow through a review pipeline of immutable
ProductChangerecords — a full audit trail of who changed what and who approved it. ProductChangeActiontypes:UPDATE,VARIANT_ADD/VARIANT_UPDATE/VARIANT_REMOVE,ATTRIBUTE_ADD/ATTRIBUTE_UPDATE/ATTRIBUTE_REMOVE,STATUS_CHANGE,PRODUCT_ADD,PRODUCT_DELETE.- Status lifecycle:
pending→confirmed/declined/canceled, orrequires_actionwhen a revision is requested. Low-risk edits auto-confirm without operator review. - Vendors see their own pending edits and revision requests on product pages.
Catalog & Inventory
- Marketplace-wide master products, variants, collections, categories, tags, and types; sellers list via offers (see above), which carry vendor-scoped price, inventory, and shipping.
- Product attributes — an operator-managed, typed attribute catalog with five types:
multi_select,single_select,text,unit,toggle. Amulti_selectattribute markedis_variant_axisgenerates product variants (backed by native MedusaProductOption). Attributes can be global (shared catalog) or inline/product-scoped (one-off); anis_filterableflag exposes them as storefront filters. Products attach attributes through a single batch endpoint. - Price lists and price preferences per vendor and region.
- Inventory items and stock locations (offer-scoped stock).
- Bulk product CSV import / export.
Shipping & Fulfillment
- Vendor-configured shipping profiles, options, and option types.
- Vendor-level fulfillment sets and fulfillment providers.
- Region- and tax-region-aware rate calculation through the Store API.
Promotions & Campaigns
- Vendor-level promotions and campaigns scoped to that vendor's catalog.
- Platform-wide promotions configurable from the Admin Panel.
Returns & Requests
- Vendor-driven return workflows with vendor-defined return reasons.
- Seller-initiated approval requests (product publish, returns, refunds).
Reviews
- Customer reviews for products and sellers.
- Admin, vendor, and customer routes.
- Aggregate rating exposed on public seller storefronts.
Search & Discovery
- Optional Algolia and Meilisearch integrations with admin UI for re-indexing.
Notifications & Communication
- In-app vendor notification feed.
- Vendor ↔ customer messaging.
Wishlist
- Customer wishlists with admin moderation routes.
Admin Panel Capabilities
- Manage all sellers (list, detail, approvals, professional and payment details, deactivation).
- Configure commission rates and platform-wide rules.
- Monitor all payouts across the marketplace.
- Marketplace configuration: currencies, sales channels, regions, tax regions, locations.
- Platform-wide catalog configuration: attributes, product types, tags, categories, collections, price lists.
- Admin user, role, and API key management.
- View every order, fulfillment, and return across sellers.
Vendor Portal Capabilities
- Manage offers against master products (SKU, price, inventory, shipping); submit product edits through the change-request pipeline and track their approval status.
- Manage variants, collections, categories, tags, types, and attributes.
- View, fulfill, and refund orders; process returns.
- Configure shipping profiles, fulfillment, and return reasons.
- Create promotions and campaigns scoped to their catalog.
- Manage customers and customer groups.
- Track payouts, configure payout accounts, complete provider onboarding.
- Store profile and settings; invite and manage team members.
- Authentication (register, login, password reset, accept invite).
Developer & Extensibility Features
Dashboard SDK (@mercurjs/dashboard-sdk)
- Vite plugin shared by admin and vendor apps.
- File-based routing — drop a file in
src/routes/and the page is registered. - Automatic navigation generation with labels, icons, rank, nesting, i18n namespaces.
- Component overrides for layout primitives (sidebars, topbar, store setup, onboarding fields).
- Build-time configuration for backend/vendor URLs and i18n.
Dashboard Shared (@mercurjs/dashboard-shared)
- Reusable React UI primitives, hooks, and form/table utilities used by both panels.
- Built on Medusa UI, Radix, and TanStack Query / Table.
Typed API Client (@mercurjs/client)
- Fully typed fetch wrapper for the Admin, Vendor, and Store APIs.
- Types are generated from real route definitions, so requests and responses stay in sync with the backend.
- Route-based access pattern:
sdk.admin.entities.$id.query({ $id }),sdk.admin.entities.mutate(payload).
Core Plugin (@mercurjs/core)
- Installed as a standard Medusa plugin and provides every marketplace module, link, workflow, API route, and subscriber.
- Extended through Medusa's normal extension model: custom modules, module links, workflow hooks, subscribers, and additional API routes inside the consuming project.
Blocks & Registry
- Blocks are the primary way marketplace features ship — distributed as source code, not packages. The CLI copies files directly into the project, so you own every line (no hidden abstractions or version conflicts). A block can bundle modules, workflows, API routes, links, and vendor/admin UI extensions; installation may require registering a module, adding middlewares, running migrations, and codegen.
- Updates are explicit:
bunx @mercurjs/cli@rc diff <block>shows upstream changes; re-install with--overwrite. - Registries catalog blocks via a
registry.json(file typesregistry:module/:workflow/:api/:link/:vendor/:admin/:lib, with dependencies).bunx @mercurjs/cli@rc buildembeds file contents into JSON, which can be hosted on any static host (GitHub Pages, S3, …). Custom registries can be added toblocks.jsonwith optional auth headers.
Templates
- basic — full-stack marketplace monorepo (API, admin, vendor) with Turborepo, ready for production.
- plugin — npm-publishable Mercur plugin scaffold for sharing modules, providers, workflows, and UI.
AI Integration
llms.txtexposes the full documentation to any LLM.- MCP server lets editors (Cursor, VS Code, Claude Code) search Mercur docs live.
- Pre-built Skills ship in every project to guide agents through page, form, tab, and component migrations.
- The typed client, monorepo layout, exposed workflows, dashboard SDK, and pluggable payout providers give AI agents structured contracts to extend rather than guess at.
System Layout
+---------------------------------------------------------------+
| Storefront (any framework) ─ Store API (/store/*) |
+---------------------------------------------------------------+
| Vendor Portal (port 7001) ─ Vendor API (/vendor/*) |
| Admin Panel (port 7000) ─ Admin API (/admin/*) |
+---------------------------------------------------------------+
| Mercur Core Plugin (@mercurjs/core) |
| Modules: Seller · Commission · Offer · Payout · |
| Product Attribute · Product Edit (change pipeline) · |
| Order Group · Media · Custom Fields · |
| Admin UI · Vendor UI · Codegen |
+---------------------------------------------------------------+
| Medusa Framework (core commerce) |
| Products · Pricing · Cart · Orders · Promotions · Payments |
+---------------------------------------------------------------+
| Postgres · Redis · Payout Provider |
+---------------------------------------------------------------+
Constraints
- Runtime: Node.js + Bun. The repo enforces
bunas the only package manager. - Database: PostgreSQL (Medusa requirement).
- Framework lock: peer-pinned to
@medusajs/framework>=2.22.0across core and providers (the workspace resolves 2.22.0). - Languages: TypeScript end-to-end; React 18 for the dashboards.
- License: MIT, open-core. No transaction fees, no commercial lock-in, no hosted vendor required.
- Payout providers: only Stripe Connect ships out of the box (in the Stripe connector plugin); others implement
IPayoutProviderfrom@mercurjs/types.
Distribution Surface
@mercurjs/core— marketplace plugin for the Medusa server.@mercurjs/client— typed API client.@mercurjs/types— shared TypeScript contracts.@mercurjs/dashboard-sdk— Vite plugin and types for admin/vendor extensibility.@mercurjs/dashboard-shared— shared dashboard primitives.@mercurjs/admin— admin panel UI package.@mercurjs/vendor— vendor portal UI package.@mercurjs/stripe-connector-plugin— Stripe payment provider, Stripe Connect payout provider and the Stripe admin/vendor screens.- Templates (
basic,plugin) — starter scaffolds.