repository·main·Indexed 23 days ago
https://github.com/mercurjs/mercurAn open-source, headless marketplace platform built on top of Medusa. It provides primitives for multi-vendor commerce, including vendor onboarding, commissions, and automated payouts, to support the development of B2B or B2C marketplaces.
The Split Order Payment Module is a standalone package in Mercur designed for multi-vendor marketplaces. It enables tracking of payment amounts (authorized, captured, refunded) separately for each seller's portion of a multi-vendor order.
Key features include:
Mercur is an open-core marketplace platform built on top of the Medusa Framework. While Medusa provides the core commerce engine (products, pricing, carts, orders, fulfillment, and events), Mercur adds a marketplace domain layer including:
The Payout Module is a standalone package in Mercur that provides out-of-the-box seller payout features. It is designed to handle the lifecycle of marketplace funds moving from the platform to sellers.
Key Features:
The Vendor Panel is a platform for vendors to manage their online store operations. Key functional areas include:
Mercur is an open-source (MIT licensed) marketplace platform designed as an alternative to closed-source SaaS providers like Mirakl.
Key differentiators include:
bun create mercur-app.Mercur exposes three distinct HTTP surfaces on the Medusa server. Choose the surface based on your target audience and required permissions:
/admin/*): For marketplace operators. Requires Medusa admin authentication (session or bearer token)./vendor/*): For sellers. Requires member authentication and is scoped to a specific seller via the x-seller-id header or a session-selected seller. This surface automatically filters all queries and mutations to the selected seller./store/*): For storefronts. Mostly public. Customer authentication is required for /store/order-groups and optional for routes like /store/offers, /store/products, and /store/search to enrich pricing context.All requests and responses use JSON. It is highly recommended to use the typed @mercurjs/client for all calls.
The Marketplace Module provides out-of-the-box features for managing multi-vendor commerce. Key features include:
OrderSet for unified tracking.In Mercur, you interact with these features by building Workflows using pre-built workflows provided in the @mercurjs/b2c-core package.
The Mercur Basic Template is a monorepo managed by Turborepo. The core structure is as follows:
apps/admin/: Admin dashboard extensions.apps/vendor/: Vendor portal extensions.packages/api/: The core backend (based on Medusa) containing:src/api/: Custom API routes.src/jobs/: Background jobs.src/links/: Module links.src/modules/: Custom modules.src/scripts/: CLI scripts.src/subscribers/: Event subscribers.src/workflows/: Business workflows.medusa-config.ts: Backend configuration.blocks.json: Configuration for Mercur blocks.turbo.json: Turborepo configuration.├── apps/
│ ├── admin/ # Admin dashboard extensions
│ └── vendor/ # Vendor portal extensions
├── packages/
│ └── api/ # Medusa backend
│ ├── src/
│ │ ├── api/ # Custom API routes
│ │ ├── jobs/ # Background jobs
│ │ ├── links/ # Module links
│ │ ├── modules/ # Custom modules
│ │ ├── scripts/ # CLI scripts
│ │ ├── subscribers/ # Event subscribers
│ │ └── workflows/ # Business workflows
│ └── medusa-config.ts
├── blocks.json # Mercur blocks configuration
├── package.json
└── turbo.jsonThe ICommissionModuleService interface provides low-level access to the Commission Module's functionalities. It is intended for developers implementing complex customizations. For standard use cases, you should use the available built-in workflows instead.
The interface is organized into several method groups:
Methods for managing rules: createCommissionRules, updateCommissionRules, deleteCommissionRules, retrieveCommissionRule, listCommissionRules, listAndCountCommissionRules, softDeleteCommissionRules, and restoreCommissionRules.
Methods for managing rates: createCommissionRates, updateCommissionRates, deleteCommissionRates, retrieveCommissionRate, listCommissionRates, listAndCountCommissionRates, softDeleteCommissionRates, and restoreCommissionRates.
Methods for managing lines: createCommissionLines, updateCommissionLines, deleteCommissionLines, retrieveCommissionLine, listCommissionLines, listAndCountCommissionLines, softDeleteCommissionLines, and restoreCommissionLines.
Includes specialized logic like selectCommissionForProductLine.
The Seller Module maintains several stored links to other Commerce Modules to associate sellers with their respective data models. These include:
| Second Data Model | Type | Description |
|---|---|---|
| Product | Stored - one-to-many | Associates a seller with their products |
| Order | Stored - one-to-many | Associates a seller with their orders |
| Return | Stored - one-to-many | Associates a seller with order returns |
| PayoutAccount | Stored - one-to-one | Associates a seller with their payout account |
| StockLocation | Stored - one-to-many | Associates a seller with their stock locations |
| FulfillmentSet | Stored - one-to-many | Associates a seller with their fulfillment sets |
| ServiceZone | Stored - one-to-many | Associates a seller with their service zones |
| ShippingOption | Stored - one-to-many | Associates a seller with their shipping options |
| ShippingProfile | Stored - one-to-many | Associates a seller with their shipping profiles |
| InventoryItem | Stored - one-to-many | Associates a seller with their inventory items |
| CustomerGroup | Stored - one-to-many | Associates a seller with their customer groups |
| PriceList | Stored - one-to-many | Associates a seller with their price lists |
| Promotion | Stored - one-to-many | Associates a seller with their promotions |
| Campaign | Stored - one-to-many | Associates a seller with their campaigns |