This document guides you through the different documentation resources that will help you build a marketplace with Medusa.
A marketplace is an online commerce store that allows different vendors to sell their products within the same commerce system. Customers can purchase products from any of these vendors, and vendors can manage their orders separately.
Associate Entities with Stores
Entities represent tables in the database.
By default, entities like users, products, or orders aren't associated with a store, as it's assumed there's one store in Medusa. For a marketplace, each of these entities should be associated with their respective stores.
To associate these entities with the
Store entity, you need to extend and customize entities created in the Medusa core package
@medusajs/medusa, such as the
User entity, to add a relation to the
Learn how to extend an entity in Medusa.
Example: Associate User with Store
Accessing Logged-in User
Throughout your development, you'll likely need access to the logged-in user. For example, you'll need to know which user is logged in to know which store to associate a new product with.
Learn how to access the logged-in user throughout your project using a Middleware.
Customize Data Management Functionalities
After associating entities with stores, you'll need to customize how certain data management functionalities are implemented in the Medusa core package.
For example, when a new user is created, you need to ensure that it's associated either with a new store or with the store of the logged-in user. Another example is associating a new product with the logged-in user's store.
You can customize these functionalities by extending services. Services are classes that contain helper methods specific to an entity. For example, the
UserService is used to manage functionalities related to the
User entity, such as creating a user.
You can also extend services if you need to customize a functionality implemented in a service for other reasons.
Learn how to extend a service in Medusa
Example: Extend User Service
Listening to Events
While implementing your marketplace, you'll typically need to listen to certain events then perform actions asynchronously. For example, you can listen to the
order.placed event and, when triggered, create child orders of the order, separating ordered items by their associated store.
To listen to events, you need to create Subscribers that subscribe a handler function to an event. In that handler function, you can implement the desired functionality.
Learn how to create a subscriber in Medusa.
Example: Listen to Order Created Event
Add Payment and Fulfillment Providers
Payment and fulfillment providers can be added through plugins or directly in your project. You can either create your own provider, use one of Medusa's official plugins, or use community plugins.
Payment and fulfillment providers are associated with regions, which are not associated with a store, by default. If you want to allow each store to specify its own payment and fulfillment providers, you'll need to associate the region with a store.
Option 1: Create your own providers
Learn how to create a payment processor.
Learn how to create a fulfillment provider.
Option 2: Install a Plugin
Check out available Medusa plugins to install.
Check out available community plugins to install.
As you add marketplace features to your store, you'll most likely need to customize the admin to provide an interface to manage these features.
Medusa's admin plugin can be extended to add widgets or new blocks to existing pages, add UI routes to add new pages, or add setting pages.
Learn how to add widgets into existing admin pages.
Learn how to add new pages to your Medusa admin.
Learn how to add new page to the Medusa admin settings.
Implement Role-Based Access Control
In your marketplace, you may need to implement role-based access control (RBAC) within stores. This will restrict some users' permissions to specified functionalities or API Routes.
If you want to implement this functionality, you can follow the RBAC recipe.
Learn how to implement role-based access control (RBAC) in Medusa.
Build a Storefront
Medusa provides a Next.js Starter Template that you can use with Medusa. Since you've customized your Medusa project, you'll need to either customize the existing Next.js Starter Template, or create a custom storefront.
Install the Next.js Starter Template to customize it.
Find useful resources to build your own storefront.
Our documentation includes deployment guides for a basic Medusa backend. You should be able to follow it to deploy your customized marketplace, as well.
Learn how to deploy your marketplace backend to different hosting providers.
You can find other resources for your marketplace development in the Medusa Development section of this documentation.