Extending Medusa Example: Creating a Marketplace

Apr 18, 2023 by

Shahed  avatar

Shahed Nasser

Shahed  avatar

Shahed Nasser

Learn how to create the foundation of your marketplace with Medusa

Extending Medusa Example: Creating a Marketplace - Featured image

Article outdated Please go to our [Marketplace Recipe](https://docs.medusajs.com/recipes/marketplace) for an up-to-date guide on setting up a marketplace with Medusa.

Medusa is the set of commerce building blocks that developers can use to create their custom use case. Instead of forcing developers to use a standardized solution, leading them to enforce hacky-workarounds, Medusa embraces customization and extendability.

This tutorial gives an example of Medusa's extensibility, showcasing how you can create a marketplace with our building blocks. While the steps in this tutorial may not lead to a fully-fledged marketplace, they will give you an idea of how it can be implemented by building the foundation. You’ll also find other resources at the end of the tutorial that can guide you through the rest of your marketplace development.

Last year, we wrote a blog about how to create a marketplace with Medusa and Medusa Extender. At the time, Medusa did not provide the necessary functionalities to extend its core, which required developers to use Medusa Extender. With the release of v1.8 of Medusa, the marketplace can now be built with Medusa only. This tutorial illustrates how to do that.

The code of this tutorial is available in this GitHub Repository.

What You’ll be Building

By following along the steps in this tutorial, you’ll be implementing the following logic:

  1. Every time a user is created, a new store associated with that user is created.
  2. When the user retrieves the store’s details, their store’s details will be retrieved.
  3. Every time a product is created, it is associated with the store of the logged-in user.
  4. The user will only be able to retrieve products from their store.

Prerequisites

This article assumes you already have a Medusa backend with v1.8 of Medusa installed. If not, you can learn how to install it here.

Extend the Store Entity

In this section, you’ll extend the Store entity so that you can later add new relations to it. Extending an entity requires extending its repository as well.

You can learn more about extending an entity in our documentation.

Create the file Copy to clipboardsrc/models/store.ts with the following content:

import { Entity } from "typeorm"
import {
Store as MedusaStore,
} from "@medusajs/medusa"
@Entity()
export class Store extends MedusaStore {
// TODO add relations
}

This imports the Copy to clipboardStore entity from the Medusa core package as Copy to clipboardMedusaStore and creates a new Copy to clipboardStore entity that extends it.

Extend the StoreRepository

Next, create the file Copy to clipboardsrc/repositories/store.ts with the following content:

import { Store } from "../models/store"
import {
dataSource,
} from "@medusajs/medusa/dist/loaders/database"
import {
StoreRepository as MedusaStoreRepository,
} from "@medusajs/medusa/dist/repositories/store"
export const StoreRepository = dataSource
.getRepository(Store)
.extend({
...Object.assign(
MedusaStoreRepository,
{ target: Store }
),
})
export default StoreRepository

This imports the Copy to clipboardStoreRepository from the Medusa core package as Copy to clipboardMedusaStoreRepository, then extends the repository to target the new Copy to clipboardStore entity you created.

Create index.d.ts

Finally, to ensure TypeScript is aware of the new type you’re creating, create the file Copy to clipboardsrc/index.d.ts with the following content:

export declare module "@medusajs/medusa/dist/models/store" {
declare interface Store {
// TODO add relations
}
}

You’ll later add relations to the Copy to clipboardStore interface as you add them to the Copy to clipboardStore entity. You’ll also be using the same file when extending other entities.

Extend the User Entity

Next, you’ll extend the user entity to add a new column and relation to the Copy to clipboardStore entity. The steps are the same as the ones described in the previous section.

Start by creating the Copy to clipboardsrc/models/user.ts file with the following content:

import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm"
import {
User as MedusaUser,
} from "@medusajs/medusa"
import { Store } from "./store";
@Entity()
export class User extends MedusaUser {
@Index("UserStoreId")
@Column({ nullable: true })
store_id?: string;
@ManyToOne(() => Store, (store) => store.members)
@JoinColumn({ name: 'store_id', referencedColumnName: 'id' })
store?: Store;
}

This imports the Copy to clipboardUser entity from the Medusa core package as Copy to clipboardMedusaUser and creates a new entity Copy to clipboardUser that extends it. In the entity, you add a new column Copy to clipboardstore_id and a relation Copy to clipboardstore to the Copy to clipboardStore entity.

Then, in the Copy to clipboardStore entity created in Copy to clipboardsrc/models/store.ts, add the following relation to the entity:

import { Entity, OneToMany } from "typeorm"
import { User } from "./user";
// other imports...
@Entity()
export class Store extends MedusaStore {
@OneToMany(() => User, (user) => user?.store)
members?: User[];
}

You might see some TypeScript errors in your editor now. This can be resolved by replacing the content of the Copy to clipboardsrc/index.d.ts with the following content:

export declare module "@medusajs/medusa/dist/models/store" {
declare interface Store {
members?: User[];
}
}
export declare module "@medusajs/medusa/dist/models/user" {
declare interface User {
store_id?: string;
store?: Store;
}
}

This informs TypeScript that the Copy to clipboardUser entity now has Copy to clipboardstore_id and Copy to clipboardstore properties, and the Copy to clipboardStore entity has a Copy to clipboardmembers property. You can learn more here.

Extend the UserRepository

Next, create the file Copy to clipboardsrc/repositories/user.ts with the following content:

import { User } from "../models/user"
import {
dataSource,
} from "@medusajs/medusa/dist/loaders/database"
import {
UserRepository as MedusaUserRepository,
} from "@medusajs/medusa/dist/repositories/user"
export const UserRepository = dataSource
.getRepository(User)
.extend({
...Object.assign(
MedusaUserRepository,
{ target: User }
),
})
export default UserRepository

This imports the Copy to clipboardUserRepository from the Medusa core package as Copy to clipboardMedusaUserRepository and creates a new Copy to clipboardUserRepository that extends it but targets the new Copy to clipboardUser entity.

Create Migration for the User Entity

Since you’re adding a new column Copy to clipboardstore_id to the Copy to clipboardUser entity, you must add a new migration that reflects that column in your database.

You can learn more about migrations in our documentation.

First, run the following command in the root directory of your backend:

npx typeorm migration:create src/migrations/add-user-store-id

This will create a new file under Copy to clipboardsrc/migrations. The file’s name should be of the format Copy to clipboard<TIMESTAMP>_UserChanged.ts.

In the file, there’s a migration class with two methods: Copy to clipboardup and Copy to clipboarddown. Replace the methods with the following content:

public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`ALTER TABLE "user" ADD "store_id" character varying`);
await queryRunner.query(`CREATE INDEX "UserStoreId" ON "user" ("store_id") `);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`DROP INDEX "public"."UserStoreId"`);
await queryRunner.query(`ALTER TABLE "user" DROP COLUMN "store_id"`);
}

Before you run the migrations, run the Copy to clipboardbuild command which transpiles the files under the Copy to clipboardsrc directory into the Copy to clipboarddist directory:

npm run build

Then, run the migration command:

medusa migrations run

This will add the new Copy to clipboardstore_id column to the Copy to clipboarduser table.

Create Middleware to Register Logged-In User

To get access to the logged-in user across your services, you need to register it through a middleware. This middleware will run on all endpoints under the Copy to clipboard/admin path, except for the Copy to clipboard/admin/auth endpoints.

You can learn more about middlewares in our documentation.

Start by creating the file Copy to clipboardsrc/api/middlewares/logged-in-user.ts with the following content:

import { UserService } from "@medusajs/medusa"
import { User } from "../../models/user"
export async function registerLoggedInUser(req, res, next) {
let loggedInUser: User | null = null
if (req.user && req.user.userId) {
const userService =
req.scope.resolve("userService") as UserService
loggedInUser = await userService.retrieve(req.user.userId)
}
req.scope.register({
loggedInUser: {
resolve: () => loggedInUser,
},
})
next()
}

This retrieves the logged-in user from Copy to clipboardreq.user.userId and, if available, registers it in Medusa’s dependency container under Copy to clipboardloggedInUser.

You can learn more about the dependency container and injection in our documentation.

Next, create the file Copy to clipboardsrc/api/index.ts with the following content:

import { Router } from "express"
import configLoader from "@medusajs/medusa/dist/loaders/config"
import {
registerLoggedInUser,
} from "./middlewares/logged-in-user"
import
authenticate
from "@medusajs/medusa/dist/api/middlewares/authenticate"
import * as cors from "cors"
export default function (rootDirectory: string) {
const router = Router()
const config = configLoader(rootDirectory)
const adminCors = {
origin: config.projectConfig.admin_cors.split(","),
credentials: true,
}
router.use(
/\/admin\/[^(auth)].*/,
cors(adminCors),
authenticate(),
registerLoggedInUser
)
return router
}

This registers the middleware on all paths starting with Copy to clipboard/admin except for Copy to clipboard/admin/auth paths. Notice that you also add the Copy to clipboardauthenticate middleware before the Copy to clipboardregisterLoggedInUser middleware. The Copy to clipboardauthenticate middleware authenticates the user and sets Copy to clipboardreq.user. If not added, the Copy to clipboardregisterLoggedInUser middleware will not be able to access the logged-in user.

You’ll see the middleware’s work in action when you start customizing services in the upcoming sections.

Extend Store Service

In this section, you’ll extend the Copy to clipboardStore service to change the logic behind retrieving a store. In the Medusa core package, it’s assumed there’s one store and so the first store is retrieved. You’ll be changing that to retrieve the store of the logged-in user.

You can learn more about extending services in the documentation.

Create the file Copy to clipboardsrc/services/store.ts with the following content:

import { Lifetime } from "awilix"
import {
FindConfig,
StoreService as MedusaStoreService, Store, User,
} from "@medusajs/medusa"
class StoreService extends MedusaStoreService {
static LIFE_TIME = Lifetime.SCOPED
protected readonly loggedInUser_: User | null
constructor(container, options) {
// @ts-expect-error prefer-rest-params
super(...arguments)
try {
this.loggedInUser_ = container.loggedInUser
} catch (e) {
// avoid errors when backend first runs
}
}
async retrieve(config?: FindConfig<Store>): Promise<Store> {
if (!this.loggedInUser_) {
return super.retrieve(config);
}
return this.retrieveForLoggedInUser(config);
}
async retrieveForLoggedInUser (config?: FindConfig<Store>) {
const storeRepo = this.manager_.withRepository(this.storeRepository_);
const store = await storeRepo.findOne({
...config,
relations: [
...config.relations,
'members'
],
where: {
id: this.loggedInUser_.store_id
},
});
if (!store) {
throw new Error('Unable to find the user store');
}
return store
}
}
export default StoreService

You import the Copy to clipboardStoreService from the Medusa core package as Copy to clipboardMedusaStoreService. You then create a new Copy to clipboardStoreService class that extends Copy to clipboardMedusaStoreService.

In the class, you set the Copy to clipboardLIFE_TIME of the service to Copy to clipboardLifetime.SCOPED. This is necessary for the service to access the registered Copy to clipboardloggedInUser. You can learn more about it in the documentation.

You also add a new class attribute Copy to clipboardloggedInUser_ and set its value in the constructor. Notice that you wrap the initialization of Copy to clipboardloggedInUser_ in the constructor with a try-catch block to avoid errors when the Copy to clipboardloggedInUser is not registered in the Medusa container.

You then override the Copy to clipboardretrieve method. In that method:

  1. You check if the Copy to clipboardloggedInUser_ is set. If not, you call the Copy to clipboardretrieve method of the service from the core package.
  2. If the Copy to clipboardloggedInUser_ is set, you retrieve the store using a new method Copy to clipboardretrieveForLoggedInUser. This method retrieves the store using the value of Copy to clipboardstore_id of the Copy to clipboardloggedInUser_ and expands the Copy to clipboardmembers relation.

Before you test out this method, you should create the logic that associate a new user with a new store.

Extend the User Service

In this section, you’ll implement the logic behind creating a store for every new user. To do this, you’ll extend the Copy to clipboardUserService from the Medusa core to override the Copy to clipboardcreate method.

Create the file Copy to clipboardsrc/services/user.ts with the following content:

import { Lifetime } from "awilix"
import { UserService as MedusaUserService } from "@medusajs/medusa"
import { User } from "../models/user"
import { CreateUserInput as MedusaCreateUserInput } from "@medusajs/medusa/dist/types/user"
import StoreRepository from "../repositories/store"
type CreateUserInput = {
store_id?: string
} & MedusaCreateUserInput
class UserService extends MedusaUserService {
static LIFE_TIME = Lifetime.SCOPED
protected readonly loggedInUser_: User | null
protected readonly storeRepository_: typeof StoreRepository;
constructor(container, options) {
// @ts-expect-error prefer-rest-params
super(...arguments)
this.storeRepository_ = container.storeRepository
try {
this.loggedInUser_ = container.loggedInUser
} catch (e) {
// avoid errors when backend first runs
}
}
async create(user: CreateUserInput, password: string): Promise<User> {
if (!user.store_id) {
const storeRepo = this.manager_.withRepository(this.storeRepository_)
let newStore = storeRepo.create()
newStore = await storeRepo.save(newStore)
user.store_id = newStore.id
}
return await super.create(user, password)
}
}
export default UserService

In this file you:

  1. Extend the core’s Copy to clipboardUserService which is imported as Copy to clipboardMedusaUserService.
  2. You change the value of the Copy to clipboardLIFE_TIME attribute of the service. This is explained in the Extend Store Service section.
  3. You add a new Copy to clipboardloggedInUser_ attribute and initialize it in the constructor.
  4. You override the Copy to clipboardcreate method. In the method, you first check if the Copy to clipboarduser does not have a Copy to clipboardstore_id. This allows you to specifically set the store of the user in other places if necessary. This can be helpful if you’re creating a team of users in one store. If the user doesn’t have Copy to clipboardstore_id set, a new store is created and the Copy to clipboardstore_id property of the user is set to the ID of the new store. The user is saved then using the logic implemented in the core service.

Test Store-User Relation

Time to test everything you’ve implemented so far. To do that, run the Copy to clipboardbuild and the Copy to clipboardstart commands in your Medusa backend:

npm run build && npm start

Once your Medusa backend starts, login with any admin user that you have using the User Login endpoint. If you’ve seeded your database with demo data, you should have the following login credentials:

{
"email": "admin@medusa-test.com",
"password": "supersecret"
}

Notice that when you log in, the Copy to clipboardstore_id of the user is set to Copy to clipboardnull.

Then, try to get the store’s data using the Get Store Details endpoint. The default store will be returned, which has an empty Copy to clipboardmembers array.

OX8ssLkIVT

Next, try to create a new user using the Create a User endpoint. You should see that the new user has a set Copy to clipboardstore_id.

etbiKy1y-V

Now, try to login with your new user, then try to retrieve the store’s data using the Get Store Details endpoint as mentioned earlier. You’ll see now that a different store is retrieved than the first time. This is the store that was created for this new user. It also has the new user as part of its Copy to clipboardmembers array.

qbgFHLKKEe

The user-store relation is now established and ready for use. Next, you’ll be working on the product-store relation.

Extend the Product Entity

In this section, you’ll extend the Copy to clipboardProduct entity to add a new column and relation to the Copy to clipboardStore. The process will be very similar to that of extending the Copy to clipboardUser entity.

Start by creating the file Copy to clipboardsrc/models/product.ts with the following content:

import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm"
import {
Product as MedusaProduct,
} from "@medusajs/medusa"
import { Store } from "./store";
@Entity()
export class Product extends MedusaProduct {
@Index("ProductStoreId")
@Column({ nullable: true })
store_id?: string;
@ManyToOne(() => Store, (store) => store.products)
@JoinColumn({ name: 'store_id', referencedColumnName: 'id' })
store?: Store;
}

This imports the Copy to clipboardProduct entity from the Medusa core package as Copy to clipboardMedusaProduct and creates a new entity Copy to clipboardProduct that extends it. In the entity, you add a new column Copy to clipboardstore_id and a relation Copy to clipboardstore to the Copy to clipboardStore entity.

Then, in the Copy to clipboardStore entity created in Copy to clipboardsrc/models/store.ts, add the following relation to the entity:

import { Product } from "./product";
// other imports...
@Entity()
export class Store extends MedusaStore {
// other relation...
@OneToMany(() => Product, (product) => product?.store)
products?: Product[];
}

You might see some TypeScript errors in your editor now. This can be resolved by adding the Copy to clipboardproducts relation to the Copy to clipboardStore interface and adding a new declaration for the Copy to clipboardProduct in Copy to clipboardindex.d.ts:

export declare module "@medusajs/medusa/dist/models/store" {
declare interface Store {
members?: User[];
products?: Product[];
}
}
// user declaration...
export declare module "@medusajs/medusa/dist/models/product" {
declare interface Product {
store_id?: string;
store?: Store;
}
}

Extend the ProductRepository

Next, create the file Copy to clipboardsrc/repositories/product.ts with the following content:

import { Product } from "../models/product"
import {
dataSource,
} from "@medusajs/medusa/dist/loaders/database"
import {
ProductRepository as MedusaProductRepository,
} from "@medusajs/medusa/dist/repositories/product"
export const ProductRepository = dataSource
.getRepository(Product)
.extend({
...Object.assign(
MedusaProductRepository,
{ target: Product }
),
})
export default ProductRepository

This imports the Copy to clipboardProductRepository from the Medusa core package as Copy to clipboardMedusaProductRepository and creates a new Copy to clipboardProductRepository that extends it but targets the new Copy to clipboardProduct entity.

Create Migration for the Product Entity

Since you’re adding a new column Copy to clipboardstore_id to the Copy to clipboardProduct entity, you must add a new migration that reflects that column in your database.

First, run the following command in the root directory of your backend:

npx typeorm migration:create src/migrations/ProductChanged

This will create a new file under Copy to clipboardsrc/migrations. The file’s name should be of the format Copy to clipboard<TIMESTAMP>_ProductChanged.ts.

In the file, there’s a migration class with two methods: Copy to clipboardup and Copy to clipboarddown. Replace the methods with the following content:

public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`ALTER TABLE "product" ADD "store_id" character varying`);
await queryRunner.query(`CREATE INDEX "ProductStoreId" ON "product" ("store_id") `);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`DROP INDEX "public"."ProductStoreId"`);
await queryRunner.query(`ALTER TABLE "product" DROP COLUMN "store_id"`);
}

Before you run the migrations, run the Copy to clipboardbuild command which transpiles the files under the Copy to clipboardsrc directory into the Copy to clipboarddist directory:

npm run build

Then, run the migration command:

medusa migrations run

This will add the new Copy to clipboardstore_id column to the Copy to clipboardproduct table.

Extend the Product Service

In this section, you’ll extend the product service to do two things:

  1. Change the Copy to clipboardsave logic to attach the product to the logged-in user’s store.
  2. Change the methods used to retrieve products including the Copy to clipboardlist, Copy to clipboardlistAndCount, and Copy to clipboardretrieve methods to retrieve the products only associated with the logged-in user’s store.

Create the file Copy to clipboardsrc/services/product.ts with the following content:

import { Lifetime } from "awilix"
import {
ProductService as MedusaProductService, Product, User,
} from "@medusajs/medusa"
import { CreateProductInput as MedusaCreateProductInput, FindProductConfig, ProductSelector as MedusaProductSelector } from "@medusajs/medusa/dist/types/product"
type ProductSelector = {
store_id?: string
} & MedusaProductSelector
type CreateProductInput = {
store_id?: string
} & MedusaCreateProductInput
class ProductService extends MedusaProductService {
static LIFE_TIME = Lifetime.SCOPED
protected readonly loggedInUser_: User | null
constructor(container, options) {
// @ts-expect-error prefer-rest-params
super(...arguments)
try {
this.loggedInUser_ = container.loggedInUser
} catch (e) {
// avoid errors when backend first runs
}
}
async list(selector: ProductSelector, config?: FindProductConfig): Promise<Product[]> {
if (!selector.store_id && this.loggedInUser_?.store_id) {
selector.store_id = this.loggedInUser_.store_id
}
config.select?.push('store_id')
config.relations?.push('store')
return await super.list(selector, config)
}
async listAndCount(selector: ProductSelector, config?: FindProductConfig): Promise<[Product[], number]> {
if (!selector.store_id && this.loggedInUser_?.store_id) {
selector.store_id = this.loggedInUser_.store_id
}
config.select?.push('store_id')
config.relations?.push('store')
return await super.listAndCount(selector, config)
}
async retrieve(productId: string, config?: FindProductConfig): Promise<Product> {
config.relations = [
...(config.relations || []),
'store'
]
const product = await super.retrieve(productId, config);
if (product.store?.id && this.loggedInUser_?.store_id && product.store.id !== this.loggedInUser_.store_id) {
// Throw error if you don't want a product to be accessible to other stores
throw new Error('Product does not exist in store.');
}
return product
}
async create(productObject: CreateProductInput): Promise<Product> {
if (!productObject.store_id && this.loggedInUser_?.store_id) {
productObject.store_id = this.loggedInUser_.store_id
}
return await super.create(productObject);
}
}
export default ProductService

In this file you:

  1. Extend the core’s Copy to clipboardProductService which is imported as Copy to clipboardMedusaProductService.
  2. You change the value of the Copy to clipboardLIFE_TIME attribute of the service. This is explained in the Extend Store Service section.
  3. You add a new Copy to clipboardloggedInUser_ attribute and initialize it in the constructor.
  4. You override the Copy to clipboardlist and Copy to clipboardlistAndCount methods to filter the retrieved products by the logged-in user’s store ID. You also ensure that the Copy to clipboardstore_id attribute is retrieved as part of the product and that the Copy to clipboardstore relation is expanded.
  5. You override the Copy to clipboardretrieve method to check if the retrieved product belongs to the logged-in user’s store. If not, you throw an error that the product does not exist.
  6. You override the Copy to clipboardcreate method to check if the logged-in user has a store and, if so, associate the product’s store ID with that store.
Notice that you didn’t implement the Copy to clipboardsave mechanism as part of the repository this time. This is because the repository does not have access to the Medusa container. So, you won’t be able to access the logged-in user in it.

Test the Product-Store Relation

You can now test the relation between the product and the store.

Start by running the Copy to clipboardbuild and Copy to clipboardstart commands in the root of your Medusa backend:

npm run build && npm start

Then, log in as a user who has a store as explained in the previous testing section.

After that, retrieve the available products by sending a request to the List Products endpoint. You’ll see that there are no products returned, even if you previously had products in your store. This is because these products are not associated with the user’s store.

xVOk-B0b72

Then, try creating a new product using the Create Product endpoint. You’ll see that the created product has a Copy to clipboardstore attribute. The Copy to clipboardid of that store is the same ID of the user’s store.

YJ1vvpKLNF

If you try retrieving the list of products again, you’ll find your newly-created product in the returned array.

wtqAmWmbrb

Note About Super-Admin User

So far in your implementation you’ve taken into accoun utsers that don’t have a set store ID. These are considered “super-admin” users. These users would be able to view all products in the store and the default store’s details.

If this logic does not work for you, make sure to change the implementation to require a store ID for a user in the different locations we’ve used it.

What’s Next

In this tutorial, you learned how to implement the foundation of a marketplace: having multiple stores, different users within those stores, and associating products with a store.

A marketplace has a variety of other features, each depending on your use case. Some of them are:

  • Create order-store relation: This requires a similar implementation as what you’ve done in this tutorial with products and users. You need to extend the Copy to clipboardOrder entity to include a relation to the store. You can learn more about extending entities in the documentation.
  • List orders by stores: This requires a similar implementation as what you’ve done in this tutorial with products. You need to extend the Copy to clipboardOrderService to override the methods used to retrieve orders. You can learn more about extending services in the documentation.
  • Associate an order to a store: This requires listening to the Copy to clipboardorder.created event in a subscriber. The implementation can include creating child orders of an order if in your use case you support have products from multiple stores in one product. In this case, you’d also need to extend the order entity to create a parent-child relation. You can learn more about subscribers in the documentation.
  • Implement teams within a store: You can implement a team within a store by extending the Copy to clipboardInvite entity to associate it with a store ID, then associate the user created from the invite with that store ID.

These are just some ideas and direction for your development of the marketplace. For further help in your development, make sure to check out the available guides in our documentation.

Share this post

Try Medusa

Spin up your environment in a few minutes.