Mercur

Mercur is an open-source, headless marketplace platform built on Medusa — positioned as a Mirakl-style alternative you can self-host without GMV fees or a locked SaaS runtime. I follow it when the job is real multi-vendor commerce (seller onboarding, shared catalogs with seller offers, commissions, split orders, payouts) rather than bolting “vendors” onto a single-seller cart. The GitHub monorepo, mercurjs.com, features, and v2 docs describe an MIT-licensed core plus optional Enterprise modules, with Admin, Vendor, and Storefront surfaces talking to a TypeScript / Medusa API. Setup for product work is typically bun create mercur-app@latest — clone the monorepo mainly when contributing upstream.

#What I like most about Mercur

I keep Mercur on the shortlist when marketplace primitives matter more than another B2C theme — sellers and offers are first-class, not an afterthought plugin.

#1. Marketplace domain on a real commerce core

Medusa already covers products, carts, orders, payments, shipping, tax, and stock; Mercur adds sellers, onboarding, product requests/approvals, commissions, reviews, return escalations, order splitting, and vendor payouts (docs intro).
Why it matters: You inherit a battle-tested commerce engine instead of reinventing checkout while still getting multi-vendor behavior.

#2. Master catalog + seller offers

Products are shared master catalog items; sellers attach offers (their SKU, price, inventory, shipping) against the same product — the model docs call out explicitly (Offers, Products).
Why it matters: True marketplace assortment (multiple sellers on one product) is different from “each vendor owns a private product tree.”

#3. Commissions, split orders, and payouts

Rule-based commissions (flat, percentage, or mixed by site/category/product/seller), multi-seller carts that become order groups with split seller orders, and payout plumbing integrated with Stripe Connect (features, commissions, payouts).
Why it matters: Fee math and money movement are usually the hardest parts of a marketplace build.

#4. Operator + seller workspaces

Admin panel for marketplace operators (vendors, catalog, commissions, rules) and a Vendor panel for sellers (catalog/offers, orders, payouts) — plus storefronts for B2C/B2B/hybrid browsing and checkout (site suite, README architecture).
Why it matters: You need three audiences day one: operator, seller team, and buyer — not only a storefront.

#5. Block-based ownership model

v2 docs emphasize blocks copied into your project via CLI (not opaque forever-plugins), with workflow hooks, typed clients, and registry/diff tooling for upgrades (welcome, blocks).
Why it matters: Marketplace logic is rarely “config only”; owning source in-repo reduces fork anxiety vs patching a black box.

#6. Deployment choice without a proprietary host

Plain Node.js + PostgreSQL + Redis — containers, K8s, your cloud, or air-gapped; optional Medusa Cloud if you want managed backend. Marketing also describes standalone vs connected marketplace (layer on Magento/Shopify/custom) (homepage, README deployment).
Why it matters: Brands with an existing commerce core often want marketplace as a parallel layer, not a full replatform on day one.

← Prev

Next →

#Project structure

Product shape (from README + site): independently deployable pieces over APIs.

Upstream monorepo (mercurjs/mercur) is the development workspace: @mercurjs/core, React + Vite admin/vendor dashboards, @mercurjs/cli, typed API client, dashboard SDK, Stripe Connect payout provider, integration suites. App projects from bun create mercur-app@latest are the normal path for building a marketplace.

@mercurjs/core layout (from architecture docs):

API paths: /admin/* (operators), /vendor/* (sellers), /store/* (storefront / checkout with splitting).

Mental model:

• Medusa foundation — catalog, cart, order, payment, fulfillment, events
• Mercur marketplace layer — sellers, offers, commissions, order groups / split orders, payouts, request/approval flows
• Blocks + registry — install/extend features as owned source in your project
• Panels — Admin / Vendor / Storefront consumers of those APIs

# Prerequisites (README): Node.js >= 20.x, PostgreSQL >= 13, Redis; Bun recommended
bun create mercur-app@latest my-marketplace
cd my-marketplace
bun run dev
# Backend API:  http://localhost:9000
# Admin:        http://localhost:9000/dashboard
# Vendor:       http://localhost:9000/seller
# Demo seller:  seller@mercur.dev / supersecret (seeded catalog)

Optional integrations called out upstream: Stripe Connect payouts, Resend email, Algolia/Meilisearch search — credentials in .env when enabled.

#Code analysis

Stack snapshot (README, site, monorepo package.json):

Strengths when I evaluate it:

• Real marketplace model — sellers, offers, commissions, split orders, payouts documented as product concepts
• Medusa leverage — commerce primitives you do not rebuild
• Headless / API-first — Admin, Vendor, Storefront APIs for custom UIs
• Block + CLI workflow — add, codegen, diff oriented toward owned customization (and AI-assisted extension per docs)
• No GMV fee on self-host core — cost shifts to infra and team, not platform cut

Trade-offs / caveats:

• Not PHP / Laravel — older labels that call it a “PHP script” are wrong; this is a Node/TypeScript/Medusa stack. Plan ops accordingly.
• Open-core — advanced modules (Buy Box, KYC, EAN matching, multi-channel stock sync, etc.) are marketed under Mercur Enterprise; do not assume every feature page item ships in MIT core
• Stack weight — Node, Postgres, Redis, Medusa, and marketplace domain is heavier than a simple CodeCanyon multi-vendor theme
• B2B depth varies by storefront/template — e.g. food wholesale templates (PROKITCHEN) are called out separately; confirm quote/company flows for your vertical
• Team must be comfortable extending Medusa workflows and TypeScript services

Env sketch (illustrative):

# .env — follow the create-app template; names illustrative
DATABASE_URL=postgres://user:pass@localhost:5432/mercur
REDIS_URL=redis://localhost:6379
# Stripe Connect / Resend / Algolia or Meilisearch when those integrations are enabled

#Why people use it

Skip it if you only need a single-seller shop, refuse Node/Postgres ops, or need Enterprise-only modules without budget for that tier — a thinner custom Medusa or Laravel path may be clearer.

#Conclusion

Mercur is one of the strongest open-source marketplace options I follow on the Medusa ecosystem: sellers, offers, commissions, split orders, and payouts as first-class product — not a B2C cart with a “vendor” checkbox (repo, site, features, docs, resources/blog).

Honest caveat: treat marketing feature lists as platform capability, then verify what lands in MIT core vs Enterprise for your go-live scope. And if an older brief called this a PHP script — correct the architecture assumption before staffing the build.