A marketplace is a commerce engine plus three things most engines don't give you out of the box: multiple sellers, split fulfilment, and a money-splitting problem at checkout. Medusa doesn't ship a "marketplace mode," and that's actually the right design. A marketplace has enough business-specific logic (commission tiers, payout cadence, seller-level returns policy) that a generic toggle would fight you more than it helped. What Medusa gives you instead is an extension model precise enough to build the real thing.
Model the seller as a first-class entity
Start with a seller module: a scoped record that owns its own products,
inventory, and fulfilment configuration. Every product belongs to exactly
one seller. This is the foundation everything else hangs off, and getting it
wrong (treating seller as a tag on a product instead of an owning entity)
is the most common mistake we see in marketplace rebuilds that come to us
after a first attempt stalled.
Split the order, not the checkout
The buyer should see one cart and one checkout, regardless of how many
sellers are in it. The split happens after payment authorization: group cart
line items by seller, and create a fulfillment record (or a child order,
depending on how much seller-level detail you need to expose) per seller
against the same payment_collection. Each seller only ever sees and acts on
their own slice.
| Kryeo | Bolt-on plugin approach | |
|---|---|---|
| Seller boundary | First-class module, owns products and inventory | Tag/field on existing product model |
| Checkout | Single cart, split into per-seller fulfilment post-payment | Often forces multiple checkouts or a single combined order |
| Commission | Workflow step, versionable per seller/category | Hardcoded percentage, hard to change per seller |
| Payout | Scheduled workflow against a ledger, reconciled before release | Synchronous transfer at order time, which breaks on refunds |
Commission as a workflow step, not a constant
Commission rates are a business decision that changes: per seller, per category, per promotion period. Hardcoding a percentage in the payment logic is the thing that forces an emergency deploy six months in when a seller negotiates a different rate. Model it as a step in the order-completion workflow that reads a commission rule (seller-level, with category overrides) and writes the split to a ledger entry. Medusa's workflow engine is built exactly for this: steps that can be retried, tested in isolation, and composed without touching unrelated logic.
Payouts: a ledger, not a transfer
The naive version pays the seller the moment an order completes. The real version holds the seller's share against a ledger entry, waits out the return window, and releases payouts on a schedule (daily or weekly, depending on your payment processor's settlement timing). Build the reconciliation step, matching released payouts against refunds and chargebacks, before you need it for the first dispute, not after.
Scoping a marketplace build?
We'll walk through your commission model and seller onboarding flow and tell you exactly how it maps onto Medusa's module and workflow system before you commit to a build.
Talk to an engineer →Where teams actually get stuck
Not the commerce logic. The operational surface around it: seller onboarding (KYC, bank details, tax forms), a seller-facing dashboard separate from the buyer-facing storefront, and support tooling for disputes between buyers and sellers. None of that is Medusa-specific; all of it needs to be scoped before estimating the build, because it's usually a larger share of the engineering effort than the marketplace commerce logic itself.
For the base commerce architecture this builds on top of, see is Medusa production-ready in 2026. We build these on Medusa development engagements, usually alongside a headless commerce storefront.