Extending Medusa Example: Creating a Marketplace

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:

123456789
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:

123456789101112131415161718
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:

12345
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:

12345678910111213141516
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:

123456789
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:

123456789101112
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:

123456789101112131415161718
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:

1
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:

123456789
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:

1
npm run build

Then, run the migration command:

1
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:

1234567891011121314151617181920
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:

1234567891011121314151617181920
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(

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:

1234567891011121314151617181920
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
    }
  }

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:

1234567891011121314151617181920
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

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:

1
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:

1234
{
    "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.

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.

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.

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:

12345678910111213141516
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:

12345678910
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:

123456789101112131415
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:

123456789101112131415161718
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:

1
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:

123456789
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:

1
npm run build

Then, run the migration command:

1
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:

1234567891011121314151617181920
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

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:

1
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.

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.

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

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.