How do you design a MedusaJS marketplace where each vendor runs its own catalogue and orders?

Sources checked on 10 November 2026 against the Medusa v2 documentation; the latest release on that day was v2.22.6.

This guide is for a CTO, product owner or platform operator who wants many vendors to run separate catalogues in one store and handle their own orders. It covers what you need to design in the data model, permissions and processes before the first screen of a vendor panel is built.

The short version: the Medusa core gives you products, carts, orders, authentication and extension mechanisms, but it does not give you a vendor. The vendor, its users, product ownership and order splitting are built as a custom module. The biggest risk is not the module code but data isolation: every vendor endpoint must return and change that vendor's data only.

Medusa's marketplace guide says plainly that marketplace features live in a module that defines its own data models, such as vendors. See the Medusa marketplace recipe.

The example in the documentation builds a module with two models, Vendor and VendorAdmin, and connects the vendor to products and orders through module links. A link is a separate join table, similar to a pivot table, so the core product and order tables stay untouched. See the vendors module example.

The table below separates what comes from the core and what is your design decision. It reflects the documentation on 10 November 2026; for another Medusa version, check again.

In the documentation example a vendor has a name, a unique handle and a logo, and its admins have a first name, last name and unique email. That is the technical minimum. The business model almost always needs more, and it is worth settling before the first migration.

The most common mistake is treating the vendor as a single user account. A selling company usually has several people: the owner, someone for the catalogue, the warehouse and accounting. If the vendor and its users are separate entities from the start, adding roles later does not require a rebuild.

1. Vendor states: applied, under review, active, suspended, closed. Each state decides whether offers are visible and whether orders can be placed.
2. Roles within a vendor: who can publish offers, who fulfils orders, who sees settlements.
3. Company data and documents: what the operator verifies before activation and who can change it afterwards.
4. Invitations and leavers: how to add a new vendor user and how to remove access for someone who leaves.
5. Suspension: what happens to live offers and open orders when the operator suspends a vendor.

Medusa's Auth module distinguishes actor types: the built-in admin user and store customer, plus custom types. In the documentation example a vendor admin signs in as an actor of type vendor, and the ID of their account is stored in the identity's metadata. See actor types in the Auth module.

Vendor routes are protected by the authenticate middleware with the vendor actor type. That answers the question of who is signed in. It does not answer which vendor owns the product with a given ID. You write that second check yourself, in every endpoint and every workflow that reads or changes data. See protected API routes.

A practical rule: the vendor ID always comes from the signed-in actor's context, never from a request parameter. If an endpoint accepts a product or order ID, it first checks that record's link to the actor's vendor and only then returns anything.

According to the example, Medusa Admin is meant for the platform operator, not for vendor admins. The vendor panel is a separate application using vendor routes, so its security depends entirely on those routes.

• Two-vendor test: check every endpoint with vendor A's account against vendor B's data. The expected result is denied access, not an empty list with a success code.
• Lists and search: the vendor filter also covers exports, reports and search suggestions.
• Events and notifications: a new-order email goes only to the vendor whose items are in it.
• Operator logs: record operator actions taken on behalf of a vendor, including who performed them.

In the documentation example a vendor product is created by a workflow that creates the product in the Product module, assigns it to the default sales channel and stores the link to the vendor. A Medusa workflow is a series of steps, and a step can have a compensation function that undoes its changes when the workflow fails. See workflows in Medusa.

Make sure the steps that write data have compensation. Test a link failure after the product is created and check whether the workflow deletes the product or leaves it unavailable until it is fixed. See the Medusa compensation function.

The most important product decision is whether two vendors can offer the same item. If they can, you need to separate a shared product page from the vendor's offer with its own price, stock and shipping time. If not, each vendor has its own products and you accept or moderate duplicates.

The second decision is moderation. The operator can publish offers immediately or after approval. Approval gives quality control at the cost of the vendor's time, so it is often applied only to new vendors or selected categories.

The Medusa recipe describes replicating the cart completion route and a custom workflow that splits the order into separate orders, one for each vendor. The customer places one order, and each vendor sees and fulfils only its part.

From the vendor's point of view, what matters is what it can do with its order: confirm, pack, ship, partially cancel. Design each of those actions so it changes only the vendor's part, and the state of the customer's whole order follows from the states of its parts.

Payments, vendor payouts, commissions, invoices and refunds are a separate, large topic. We cover it in the guide on how to split the cart, payments and invoices in a B2B marketplace, so we do not repeat it here.

It is worth building a Medusa marketplace the way the documentation shows: a new module, links, your own routes and workflows, with no changes to core code. Then a Medusa upgrade affects your module only where the interfaces it uses change.

Those interfaces do change. The documentation pages this guide links to carry notes about changes, for example as of v2.13.0 and v2.20.0. So record the Medusa version you design the module on, and on every upgrade run the vendor isolation and order splitting tests.

• Do not change core tables: keep product and order ownership in links, not in extra columns on core tables.
• Do not fork the core: every patch to Medusa code is a cost on every upgrade.
• Pin the version: record the Medusa version and the documentation state your decisions rely on.
• Tests on upgrade: vendor isolation, offer publishing and order splitting on a test environment before production.

The Medusa documentation pages checked on 10 November 2026 do not point to a ready-made marketplace module. They refer to example code and guides. Open source projects and third-party solutions built on Medusa exist, but you need to check their scope, licence and compatibility with your Medusa version yourself.

A ready-made module shortens the start if its vendor, catalogue and order model matches yours. A custom module makes more sense when the marketplace is the company's main product and its rules differ from what a ready-made solution expects. The questions below help settle this on facts.

These materials let the scope be assessed without guessing. A missing answer to any question is useful information too.

1. Your Medusa version, if the project is already live, and the list of custom modules and changes.
2. Catalogue model: whether two vendors can offer the same item.
3. The list of roles for vendors and for the operator.
4. Vendor states and the offer publishing rule.
5. The path of one order with items from two vendors, from cart to shipment.