Open-Source Multi-Vendor Marketplace with Medusa and Mercur

A marketplace is not a big shop, and the difference is exactly the part most tutorials skip. A shop sells one catalog; a marketplace coordinates many independent sellers through one checkout, which means vendor accounts, split orders, commission math, and payouts, all before your first customer notices anything special.

This guide walks that path on the open-source stack I run in production: Medusa as the commerce core, Mercur as the marketplace layer on top. My own marketplace serves 10,000 products from 50 vendors on this architecture, so the "parts operators underestimate" section at the end comes from operating one, not from reading about it. Every command and tier claim below was checked against the official docs and pages on August 27, 2026.

Decide these four things before you install anything

The install is one command; changing a commission model with live vendors is a migration project. Four decisions shape everything downstream:

Write these four down before touching a terminal. Every later section assumes you have answers.

What Mercur adds on top of Medusa

Mercur is an MIT-licensed marketplace platform standing on Medusa's commerce core: catalog, orders, payments, shipping, tax, and stock come from Medusa; vendor accounts, the seller panel, multi-vendor checkout with order splitting, commissions, and payouts come from Mercur. You get three surfaces from one codebase: storefront, vendor panel, and admin console.

The honest tier map matters here, so you do not plan around features you will not have. Per the editions page, checked August 27, 2026:

Everything a first marketplace launch needs sits in the MIT column. The Enterprise column is financial-operations depth, relevant once real money flows through many sellers. (Still deciding whether Medusa is the right core at all? My Medusa vs Vendure vs Saleor comparison covers that fork.) My independent Mercur review covers the maturity trade-offs in detail; this guide assumes you have decided to build.

Set up the development environment

Prerequisites, per the official docs: Node.js v20+ (LTS), Bun v1.3+ as the recommended package manager, Git, and PostgreSQL v14+. No local PostgreSQL? The docs provide a Docker one-liner running postgres:16.

Then it is one command:

bun create mercur-app@latest

The CLI asks for a project name and a template (basic or plugin), then creates the database, runs migrations, seeds demo data, and starts the dev server. Flags exist for automation: --template, --db-connection-string, --no-deps, --skip-db. After setup, three surfaces run on one port:

• API: http://localhost:9000
• Admin console: http://localhost:9000/dashboard
• Vendor panel: http://localhost:9000/seller

Restart later with bun dev. In my own runs the whole environment was up in minutes, and because Mercur inherits Medusa's operational shape, everything from my German Medusa tutorial about production (worker processes, Redis, S3-compatible storage) applies here unchanged. I deploy this stack on Railway, where individual services build in two to three minutes and deploy in parallel; with the Railway MCP server, the infrastructure side is manageable straight from an AI coding workflow.

Design the vendor onboarding flow

Mercur ships the mechanics: vendor registration, accounts, teams, and the seller panel. What it cannot ship is your policy, and that policy is a product decision:

1. Application. Open registration or invitation-only? My marketplace started invitation-only, and fifty vendors later I still think that was right.
2. Review. Who approves a vendor, against which checklist? If your vertical is regulated, this is where your own verification step lives (remember: no documented KYC feature in either Mercur tier, so treat compliance checks as your build).
3. First listing. The make-or-break moment. Watch a real, non-technical seller create their first product in the vendor panel before launch. Where they stall, your future support tickets live.
4. Activation. When does a vendor go live: first product, first stock, signed terms? Make the state explicit in the data model.

A practical test that costs one afternoon and saves weeks: run two pilot vendors through the entire flow (registration to first sale to first payout) before onboarding vendor number three.

Wire commissions and payouts

The open-source edition calculates commissions, splits payments, and executes payouts and refunds. The design work is choosing a model your vendors can predict: a percentage per category is transparent; per-vendor negotiated rates are flexible but turn every payout question into a support conversation.

Two boundaries to respect. First, the tier line: if your finance team expects a reconciliation-grade ledger and formal payout cycles, that is Enterprise scope; decide before launch, not at the first audit. Second, the payment provider's rules: split payments run through your PSP's marketplace capabilities, and onboarding vendors to the PSP (accounts, verification) is its own workflow parallel to yours.

Then test the ugly paths, because payout bugs cost trust you cannot refund: a partial refund across two vendors in one order, a commission change mid-month, a vendor leaving with pending balance. Those three cases find more real bugs than any happy-path suite I have run.

The parts operators underestimate

Everything above is plumbing; these three are the product, and each one surprised me in production:

Moderation is a daily job, not a feature. Fifty vendors means fifty opinions about product data quality. Duplicate listings, category creativity, image standards: the platform gives you tools, but someone owns the standard. Budget recurring hours, not a one-time setup.

Disputes have three parties. In a shop, a return is you and the customer. In a marketplace, it is you, the customer, and a vendor with their own margin at stake, and your platform is the referee. Write the referee's rulebook before the first dispute, because writing it during one satisfies nobody.

Vendor churn is your real growth metric. Acquiring vendors is marketing; keeping them selling is operations. The dashboards worth building early are per-vendor: time-to-first-sale, listing activity, payout reliability. A marketplace with silent vendors is a shop with extra steps.

What it costs and where to go deeper

The platform itself is the cheap part: MIT license, and my production infrastructure for this stack runs $40–60 a month on Railway with images in Cloudflare R2 for under a dollar. The real budget is development and the operational work above — my marketplace platform comparison puts numbers on that across three GMV scales, and the full case study of my own build (timeline, migration from WordPress, the pitfalls) is coming to this blog next.

If you want the shortest path to a validated decision: a two-week PoC Sprint with your real vendor model (commission math, one full payout cycle, two pilot vendors) answers more than any article. All marketplace and commerce articles live on the e-commerce topic page.