Indeed, new articles related to Medusa (and more specifically its new version 2) will be published on the perseides.org/blog website. The idea is to eventually centralize plugin-related documentation, as well as technical resources and tutorials.

So feel free to visit there to stay up to date!

In this new part, we'll be setting up Stripe and Stripe Connect to collect payments from our customers and trigger payments for our vendors.

Updating the Store entity

First, we'll add two new properties to the Store entity :

• The first property will be the Stripe account ID linked to a store

• The second property will indicate whether the Stripe account is active and ready to receive payments.

// src/models/store.ts

import { Column, Entity, OneToMany } from 'typeorm'

import { Store as MedusaStore } from '@medusajs/medusa'

import { Product } from './product'
import { User } from './user'
import { ShippingOption } from './shipping-option'
import { ShippingProfile } from './shipping-profile'
import { Order } from './order'

@Entity()
export class Store extends MedusaStore {
    @OneToMany(() => User, (user) => user.store)
    members?: User[]

    @OneToMany(() => Product, (product) => product.store)
    products?: Product[]

    @OneToMany(() => ShippingOption, (shippingOption) => shippingOption.store)
    shippingOptions?: ShippingOption[]

    @OneToMany(() => ShippingProfile, (shippingProfile) => shippingProfile.store)
    shippingProfiles?: ShippingProfile[]

    @OneToMany(() => Order, (order) => order.store)
    orders?: Order[]

    @Column({ nullable: true })
    stripe_account_id?: string

    @Column({ default: false })
    stripe_account_enabled: boolean
}

Creating the Migration

We can now apply our data to the database by creating our migration :

npx typeorm migration:create src/migrations/add-stripe-account-to-store

We can now add our changes in the up and down functions :

// src/migrations/<TIMESTAMP>-add-stripe-account-to-store.ts

// ... export class AddStripe...
    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`ALTER TABLE "store" ADD "stripe_account_id" character varying`)
        await queryRunner.query(`ALTER TABLE "store" ADD "stripe_account_enabled" boolean NOT NULL DEFAULT false`)
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`ALTER TABLE "store" DROP COLUMN "stripe_account_id"`)
        await queryRunner.query(`ALTER TABLE "store" DROP COLUMN "stripe_account_enabled"`)
    }
// ... } ...

Don't forget to apply the migrations once you have updated the file by executing this in your terminal :

yarn build
npx medusa migrations run

Configuring Medusa

In your medusa-config.js at the root of your backend directory, we'll setup the medusa-payment-stripe so that we can use it later :

// ... others

const plugins = [
  `medusa-fulfillment-manual`,
  `medusa-payment-manual`,
  {
    resolve: `@medusajs/file-local`,
    options: {
      upload_dir: "uploads",
    },
  },
  {
    resolve: "@medusajs/admin",
    /** @type {import('@medusajs/admin').PluginOptions} */
    options: {
      autoRebuild: true,
      develop: {
        open: process.env.OPEN_BROWSER !== "false",
      },
    },
  },
  {
    resolve: `medusa-payment-stripe`,
    options: {
      api_key: process.env.STRIPE_SECRET_KEY,
      capture: true, // For auto capturing the payments
    },
  },
];

// ... others

Adding the medusa-payment-stripe dependency

Before continuing, make sure you have the medusa-payment-stripe package available in your project, otherwise you can install it this way:

yarn add medusa-payment-stripe

Creating the Service

With all this groundwork done, we're finally going to create the StripeConnectService. I invite you to create a new file in the /src/services folder with the name stripe-connect.ts.

Once the file has been created, here's what you'll need to paste inside it for now :

import { TransactionBaseService, type ConfigModule as MedusaConfigModule } from '@medusajs/medusa'
import { Lifetime } from 'awilix' 
import { MedusaError } from 'medusa-core-utils'

import type StripeBase from 'medusa-payment-stripe/dist/core/stripe-base'
import type { Stripe } from 'stripe'
import type { Repository } from 'typeorm'

import type { Store } from '../models/store'

type ConfigModule = MedusaConfigModule & {
    projectConfig: MedusaConfigModule['projectConfig'] & {
        server_url: string
    }
}

type InjectedDependencies = {
    stripeProviderService: StripeBase
    storeRepository: Repository<Store>
    configModule: ConfigModule
}

class StripeConnectService extends TransactionBaseService {
    static identifier = 'stripe-connect'
    static LIFE_TIME = Lifetime.SINGLETON

    private readonly stripe_: Stripe
    private readonly serverUrl_: string
    private readonly storeRepository_: Repository<Store>

    constructor(container: InjectedDependencies) {
        super(container)

        this.stripe_ = container.stripeProviderService.getStripe()
        this.serverUrl_= container.configModule.projectConfig.server_url

        this.storeRepository_ = container.storeRepository
    }

    async createTransfer(data: Stripe.TransferCreateParams): Promise<Stripe.Transfer> {
        const transfer = await this.stripe_.transfers.create(data)
        return transfer
    }

    async createAccount(storeId: string): Promise<Stripe.Response<Stripe.Account>> {
        return await this.atomicPhase_(async (m) => {
            const storeRepo = m.withRepository(this.storeRepository_)

            const store = await storeRepo.findOne({ where: { id: storeId } })

            if (!store) {
                throw new MedusaError(MedusaError.Types.NOT_FOUND, 'Store not found')
            }

            if (store.stripe_account_id) {
                return await this.stripe_.accounts.retrieve(store.stripe_account_id)
            }

            const accountToken = await this.stripe_.tokens.create({
                account: {
                    business_type: 'company',
                    company: {
                        name: store.name,
                    },
                    tos_shown_and_accepted: true,
                },
            })

            const account = await this.stripe_.accounts.create({
                type: 'custom',
                country: 'YOUR_COUNTRY_CODE', // Replace with a supported country code, e.g. 'FR', 'US', 'ES' etc.
                account_token: accountToken.id,
                capabilities: {
                    card_payments: {
                        requested: true,
                    },
                    transfers: {
                        requested: true,
                    },
                },
            })


            await storeRepo.update(
                storeId,
                { stripe_account_id: account.id }
            )

            return account
        })
    }

    async createOnboardingLink(storeId: string) {
        const url = `${this.serverUrl_}/stripe/onboarding`

        return await this.atomicPhase_(async (m) => {
            const storeRepo = m.withRepository(this.storeRepository_)

            const store = await storeRepo.findOne({ where: { id: storeId } })

            if (!store) {
                throw new MedusaError(MedusaError.Types.NOT_FOUND, 'Store not found')
            }

            if (!store.stripe_account_id) {
                throw new MedusaError(MedusaError.Types.NOT_FOUND, 'Stripe account not found')
            }

            if (store.stripe_account_enabled) {
                throw new MedusaError(MedusaError.Types.NOT_ALLOWED, 'Stripe account already enabled')
            }

            const accountLink = await this.stripe_.accountLinks.create({
                account: store.stripe_account_id,
                type: 'account_onboarding',
                refresh_url: `${url}/refresh?storeId=${store.id}`,
                return_url: `${url}/return?storeId=${store.id}`,
            })


            if(!store.metadata) {
                store.metadata = {
                    stripe_onboarding_url: accountLink.url
                }
            } else {
                store.metadata.stripe_onboarding_url = accountLink.url
            }

            await storeRepo.save(store)
        })
    }


    async retrieveStripeAccount(storeId: string) : Promise<Stripe.Account> {
        const stripeAccountId = (await this.storeRepository_.findOne({ where: { id: storeId } })).stripe_account_id
        const stripeAccount = await this.stripe_.accounts.retrieve(stripeAccountId)
        return stripeAccount
    }
}

export default StripeConnectService

This service contains all the logic we need to carry out the following process:

• When creating a store, we'll use the StripeConnectService.createAccount function, which will allow us to create a Stripe account for the store in question.

• Once the Stripe account has been created, you can then create an onboarding link for the Store using the StripeConnectService.createOnboarding. This link will be saved directly in the store metadata in our case, but you can also add a new property to your Store entity that will store the onboarding url if you want.

• Finally, once the Stripe account of a store is active, we'll be able to trigger payments using the StripeConnect.createTransfer function once an order meets our conditions. In this example, we'll trigger a transfer when an order has been delivered and paid, of course you can adapt to your needs.

Use the service

As mentioned above, we're going to use our new service, when a new store is created.

To do this, we'll update our Subscriber responsible for monitoring the StoreService.Events.CREATED event :

import type { Logger, MedusaContainer, SubscriberArgs, SubscriberConfig } from '@medusajs/medusa'
import type { EntityManager } from 'typeorm'

import type ShippingProfileService from '../services/shipping-profile'
import type StripeConnectService from '../services/stripe-connect'
import StoreService from '../services/store'


export default async function handleStoreCreated({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
    const logger = container.resolve<Logger>("logger")

    const shippingProfileActivity = logger.activity(`Creating default shipping profile for store ${data.id}`)
    await createDefaultShippingProfile(data.id, container).catch(e => {
        logger.failure(shippingProfileActivity, `Error creating default shipping profile for store ${data.id}`)
        throw e
    })
    logger.success(shippingProfileActivity, `Default shipping profile for store ${data.id} created`)

    const stripeAccountActivity = logger.activity(`Creating stripe account for store ${data.id}`)
    await createStripeAccount(data.id, container).catch(e => {
        logger.failure(stripeAccountActivity, `Error creating stripe account for store ${data.id}`)
        throw e
    })

    logger.success(stripeAccountActivity, `Stripe account for store ${data.id} created`)

    const stripeOnboardingActivity = logger.activity(`Creating stripe onboarding link for store ${data.id}`)
    await createStripeOnboardingLink(data.id, container).catch(e => {
        logger.failure(stripeOnboardingActivity, `Error creating stripe onboarding link for store ${data.id}`)
        throw e
    })
    logger.success(stripeOnboardingActivity, `Stripe onboarding link for store ${data.id} created`)

}


async function createDefaultShippingProfile(storeId: string, container: MedusaContainer) {
    const manager = container.resolve<EntityManager>("manager")
    const shippingProfileService = container.resolve<ShippingProfileService>("shippingProfileService")
    return await manager.transaction(async (m) => {
        await shippingProfileService.withTransaction(m).createDefaultForStore(storeId)
    })
}

async function createStripeAccount(storeId: string, container: MedusaContainer) {
    const manager = container.resolve<EntityManager>("manager")
    const stripeConnectService = container.resolve<StripeConnectService>("stripeConnectService")
    return await manager.transaction(async (m) => {
        await stripeConnectService.withTransaction(m).createAccount(storeId)
    })
}

async function createStripeOnboardingLink(storeId: string, container: MedusaContainer) {
    const manager = container.resolve<EntityManager>("manager")
    const stripeConnectService = container.resolve<StripeConnectService>("stripeConnectService")
    return await manager.transaction(async (m) => {
        await stripeConnectService.withTransaction(m).createOnboardingLink(storeId)
    })
}

export const config: SubscriberConfig = {
    event: StoreService.Events.CREATED,
    context: {
        subscriberId: 'store-created-handler',
    },
}

Here we've refactored our code a little bit, to have three different functions triggered in order when a store is created, we also have a logger that will allows us to understand easily what's going on.

First it will create the default shipping profile for the new store, then it will create a Stripe account for that store and finally the onboarding link will be created and saved into the Store metadata, so we'll use it inside our Admin UI.

Update (again) our Medusa config

As you may have noticed, in our service we're extending Medusa's configuration and we've added a new property: server_url

In fact, this property doesn't exist by default, so you can add it directly to your configuration in this way to point to the url of your Medusa backend so that Stripe can redirect you back to this URL in the case of a success or error following their onboarding process.

// medusa-config.js

// ... others

/** @type {import('@medusajs/medusa').ConfigModule["projectConfig"]} */
const projectConfig = {
  jwtSecret: process.env.JWT_SECRET,
  cookieSecret: process.env.COOKIE_SECRET,
  store_cors: STORE_CORS,
  database_url: DATABASE_URL,
  admin_cors: ADMIN_CORS,
  server_url: process.env.SERVER_URL || 'http://localhost:9000'
  // Uncomment the following lines to enable REDIS
  // redis_url: REDIS_URL
};

// ...

Testing our service flow

If you try to create a new user, you should see something like this in your terminal after a few seconds :

Perfect, if you take a look at your store table in your database, you should see a store with not null metadata column, which contains the link to start Stripe's onboarding process.

On the other hand, before starting a process, we need to add the two routes that will handle the success/leave and error cases

Adding the Stripe API routes

Create the Success / Leave route

For this section, I invite you to create a new file in the /src/api/stripe/onboarding/return/route.ts folder :

// src/api/stripe/onboarding/return/route.ts

import type { Logger, MedusaRequest, MedusaResponse } from '@medusajs/medusa'
import type { EntityManager } from 'typeorm'

import { Store } from '../../../../models/store'
import type StripeConnectService from '../../../../services/stripe-connect'

export async function GET(req: MedusaRequest, res: MedusaResponse) {
    const storeId = req.query.storeId

    const logger = req.scope.resolve<Logger>('logger')

    if (!storeId) {
        logger.error('Stripe Onboarding Return Route: Missing storeId')
        return res.status(400).json({ error: 'Missing storeId' })
    }

    const stripeConnectService = req.scope.resolve<StripeConnectService>('stripeConnectService')
    const stripeAccount = await stripeConnectService.retrieveStripeAccount(storeId as string)

    if (!stripeAccount.details_submitted || !stripeAccount.payouts_enabled) {
        // Redirect to admin dashboard on onboarding not completed
        res.redirect("http://localhost:7001")
        return
    }

    const manager: EntityManager = req.scope.resolve<EntityManager>('manager')

    await manager.transaction(async (manager) => {
        const storeRepo = manager.getRepository(Store)

        let store = await storeRepo.findOne({ where: { id: storeId as string } })

        if (!store) {
            logger.error('Stripe Onboarding Return Route: Store not found')
            return res.status(404).json({ error: 'Store not found' })
        }

        if (store.stripe_account_enabled) {
            logger.error('Stripe Onboarding Return Route: Stripe account already enabled')
            return res.status(400).json({ error: 'Stripe account already enabled' })
        }

        store.stripe_account_enabled = true
        store = await storeRepo.save(store)
    })

    // Redirect to admin dashboard on success
    res.redirect("http://localhost:7001")
}

Here, in the case of a process success we retrieve the storeId from the query parameters, and then set the store.stripe_account_enabled value to true for that store. Once the value has been updated, we can redirect the user to the admin UI

But in case the user has just leaved the onboarding process, we do nothing and just redirect.

Create the Error route

For this route, in the same /src/api/stripe/onboarding folder, I invite you to create a refresh folder containing this route.ts file :

// src/api/stripe/onboarding/refresh/route.ts

import type { Logger, MedusaRequest, MedusaResponse } from '@medusajs/medusa'
import type { EntityManager } from 'typeorm'

import { Store } from '../../../../models/store'
import type StripeConnectService from '../../../../services/stripe-connect'

export async function GET(req: MedusaRequest, res: MedusaResponse) {
    const storeId = req.query.storeId
    const logger = req.scope.resolve<Logger>('logger')

    if (!storeId) {
        logger.error('Stripe Onboarding Return Route: Missing storeId')
        return res.status(400).json({ error: 'Missing storeId' })
    }

    const manager: EntityManager = req.scope.resolve<EntityManager>('manager')

    let redirectUrl = ''

    await manager.transaction(async (m) => {
        const stripeConnectService = req.scope.resolve<StripeConnectService>('stripeConnectService')
        const storeRepo = m.getRepository(Store)

        await stripeConnectService.withTransaction(m).createOnboardingLink(storeId as string)

        const store = await storeRepo.findOne({ where: { id: storeId as string } })

        redirectUrl = store.metadata.stripe_onboarding_url as string
    })

    res.redirect(redirectUrl)
}

Here, in the case of an error such as an expired URL, we can generate a new onboarding URL and redirect the user directly to it.

Update the ProductService

I suggest that you make sure that the storefront can't access products from stores that haven't activated their Stripe account, to make sure that all stores are "activated" before they can proceed with sales on our platform.

// src/services/product.ts

// ...

class ProductService extends MedusaProductService {

// ...

     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')

        const [products, count] = await super.listAndCount(selector, config)

        if (!this.loggedInUser_) {
            // In case we don't have a loggedInUser, we can deduce that it's a storefront API call
            // So we filter out the products that have a store with a Stripe account not enabled
            return [products.filter((p) => p.store.stripe_account_enabled), count]
        }

        return [products, count]
    }
// ...
}

Transfers

We will initiate money transfers only when an order has been marked as shipped and its overall status is set to completed.

However, Medusa does not automatically update an order's status to completed when the order is shipped and the payment is captured.

To address this, we need to create a new subscriber that monitors the payment status and fulfillment status. Based on these statuses, we will update the overall order status to completed.

By implementing this new subscriber, we can specifically track when an order is truly completed. Once the order is marked as completed, we can then trigger the money transfer process using our StripeConnectService.createTransfer

Create the Child Order Subscriber

This subscriber will monitor the events of the child orders (to be clearer, it will monitor the changes made by the stores), if an order has the status of payment captured, and its order has been marked as shipped, then we can update the child order's status to completed and create a transfer for the order's store :

import {
    FulfillmentStatus,
    Logger,
    MedusaContainer,
    OrderStatus,
    PaymentStatus,
    type SubscriberArgs,
    type SubscriberConfig,
} from '@medusajs/medusa'

import type { Order } from '../../models/order'
import OrderService from '../../services/order'
import StripeConnectService from 'src/services/stripe-connect'

export default async function handleOrderUpdated({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
    const logger = container.resolve<Logger>('logger')

    const orderService: OrderService = container.resolve('orderService')

    const order = await orderService.retrieve(data.id)

    if (!order.order_parent_id) {
        return
    }

    const updateActivity = logger.activity(`Updating child order statuses for the parent order ${order.order_parent_id}...`)
    await updateStatusOfChildren({
        container,
        parentOrderId: order.order_parent_id,
        updateActivity,
        logger
    })
    logger.success(updateActivity, `Child order statuses updated for the parent order ${order.order_parent_id}.`)
}

/**
 * This function is executed when a child order is updated.
 * It checks if the child order has a payment status of "captured" and a fulfillment status of "shipped".
 * If both conditions are met, it updates the child order's status to "complete", allowing a parent order to be marked as "complete" too.
 * But we also create a Stripe transfer for the store.
 */
type Options = {
    container: MedusaContainer,
    parentOrderId: string,
    updateActivity: void,
    logger: Logger
}
async function updateStatusOfChildren({
    container,
    parentOrderId,
    logger,
    updateActivity
}: Options) {

    const orderService = container.resolve<OrderService>('orderService')
    const stripeConnectService = container.resolve<StripeConnectService>('stripeConnectService')

    const parentOrder = await orderService.retrieve(parentOrderId, {
        relations: ['children'],
    })

    if (!parentOrder.children) {
        return
    }

    const ordersToComplete = parentOrder.children
        .filter((child) => child.payment_status === PaymentStatus.CAPTURED || child.payment_status === PaymentStatus.PARTIALLY_REFUNDED || child.payment_status === PaymentStatus.REFUNDED)
        .filter((child) => child.fulfillment_status === FulfillmentStatus.SHIPPED)
        .filter(
            (child) =>
                child.status !== OrderStatus.CANCELED &&
                child.status !== OrderStatus.ARCHIVED &&
                child.status !== OrderStatus.COMPLETED,
        )

    if (ordersToComplete.length === 0) {
        return
    }

    for (const order of ordersToComplete) {
        await orderService.completeOrder(order.id)

        const childOrder = await orderService.retrieveWithTotals(order.id, {
            relations: ['store']
        })


        await stripeConnectService.createTransfer({
            amount: childOrder.total - childOrder.refunded_total,
            currency: childOrder.currency_code,
            destination: childOrder.store.stripe_account_id,
            metadata: {
                orderId: childOrder.id,
                orderNumber: childOrder.display_id,
            },
        }).catch((e) => {
            logger.failure(updateActivity, `An error has occured while creating the Stripe transfer for order ${order.id}.`)
            throw e
        })
    }
}

export const config: SubscriberConfig = {
    event: [
        OrderService.Events.UPDATED,
        OrderService.Events.FULFILLMENT_CREATED,
        OrderService.Events.FULFILLMENT_CANCELED,
        OrderService.Events.GIFT_CARD_CREATED,
        OrderService.Events.ITEMS_RETURNED,
        OrderService.Events.PAYMENT_CAPTURED,
        OrderService.Events.PAYMENT_CAPTURE_FAILED,
        OrderService.Events.REFUND_CREATED,
        OrderService.Events.REFUND_FAILED,
        OrderService.Events.RETURN_ACTION_REQUIRED,
        OrderService.Events.RETURN_REQUESTED,
        OrderService.Events.SHIPMENT_CREATED,
        OrderService.Events.SWAP_CREATED,
    ],
    context: {
        subscriberId: 'child-order-updated-handler',
    },
}

Creating an Admin Widget

Now that the backend is in place, we're going to tackle the Admin UI, so that our vendors can begin the process of onboarding with Stripe to be able to receive transfers later on.

You can create a new widget file at the following path /src/admin/widgets/stripe-onboarding-widget.tsx :

import type { WidgetConfig } from "@medusajs/admin"
import type { SVGProps } from 'react'

import { useAdminStore, useLocalStorage } from 'medusa-react'

const StripeOnboardingWidget = () => {

    const { store } = useAdminStore()

    const [shouldHideMessage, setHideMessage] = useLocalStorage("dismiss_stripe_message", "false")

    if (!store || !store.metadata || !store.metadata.stripe_onboarding_url) return null

    if (store.stripe_account_enabled && shouldHideMessage === "false"){
        return <AccountActivatedDisplay hideMessage={() => setHideMessage("true")} />
    }

    if (!store.stripe_account_enabled) {
        return <ActivateAccountDisplay link={store.metadata.stripe_onboarding_url as string} />
    }

    return null
}


const ActivateAccountDisplay = ({ link }: { link: string }) => {
    return (
        <div className="bg-white/60 backdrop-blur-sm border-b-2 py-6 px-32 min-h-[10rem] fixed top-0 right-0 w-full flex items-center justify-between max-w-[calc(100%-240px)]">
            <div className="flex items-center gap-4">
                <WarningIcon className="text-amber-500" />
                <div className="space-1.5">
                    <h1 className="font-medium text-lg tracking-tight text-grey-80">Activate your Stripe Account</h1>
                    <p className="text-sm text-grey-50">
                        Activate your account to start selling your products and make a profit on the perseides platform.
                    </p>
                </div>
            </div>
            <a href={link} className="px-4 h-9 bg-grey-90 text-white rounded flex items-center text-sm font-medium hover:bg-grey-70 transition-colors duration-300">
                Activate Now
            </a>
        </div>
    )
}

const AccountActivatedDisplay = ({ hideMessage }: { hideMessage: () => void }) => {
    return (
        <div className="bg-white/60 backdrop-blur-sm border-b-2 py-6 px-32 min-h-[10rem] fixed top-0 right-0 w-full flex items-center justify-between max-w-[calc(100%-240px)]">
            <div className="flex items-center gap-4">
                <CheckIcon className="text-green-500" />
                <div className="space-1.5">
                    <h1 className="font-medium text-lg tracking-tight text-grey-80">Your account has been activated</h1>
                    <p className="text-sm text-grey-50">
                        Welcome to perseides, your products are now visible on the storefront and available to buy!
                    </p>
                </div>
            </div>
            <button onClick={hideMessage} className="px-4 h-9 bg-grey-90 text-white rounded flex items-center text-sm font-medium hover:bg-grey-70 transition-colors duration-300">
                Dismiss
            </button>
        </div>
    )
}

const WarningIcon = (props: SVGProps<SVGSVGElement>) => (<svg
    width="24"
    height="24"
    viewBox="0 0 24 24"
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
    {...props}
>
    <path
        d="M12 6C12.5523 6 13 6.44772 13 7V13C13 13.5523 12.5523 14 12 14C11.4477 14 11 13.5523 11 13V7C11 6.44772 11.4477 6 12 6Z"
        fill="currentColor"
    />
    <path
        d="M12 16C11.4477 16 11 16.4477 11 17C11 17.5523 11.4477 18 12 18C12.5523 18 13 17.5523 13 17C13 16.4477 12.5523 16 12 16Z"
        fill="currentColor"
    />
    <path
        fillRule="evenodd"
        clipRule="evenodd"
        d="M12 2C6.47715 2 2 6.47715 2 12C2 17.5228 6.47715 22 12 22C17.5228 22 22 17.5228 22 12C22 6.47715 17.5228 2 12 2ZM4 12C4 16.4183 7.58172 20 12 20C16.4183 20 20 16.4183 20 12C20 7.58172 16.4183 4 12 4C7.58172 4 4 7.58172 4 12Z"
        fill="currentColor"
    />
</svg>)

const CheckIcon = (props: SVGProps<SVGSVGElement>) => (<svg
    width="24"
    height="24"
    viewBox="0 0 24 24"
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
    {...props}
>
    <path
        d="M10.2426 16.3137L6 12.071L7.41421 10.6568L10.2426 13.4853L15.8995 7.8284L17.3137 9.24262L10.2426 16.3137Z"
        fill="currentColor"
    />
    <path
        fillRule="evenodd"
        clipRule="evenodd"
        d="M1 12C1 5.92487 5.92487 1 12 1C18.0751 1 23 5.92487 23 12C23 18.0751 18.0751 23 12 23C5.92487 23 1 18.0751 1 12ZM12 21C7.02944 21 3 16.9706 3 12C3 7.02944 7.02944 3 12 3C16.9706 3 21 7.02944 21 12C21 16.9706 16.9706 21 12 21Z"
        fill="currentColor"
    />
</svg>)

export const config: WidgetConfig = {
    zone: ["order.list.before", "product.list.before"],
}

export default StripeOnboardingWidget

Here we're injecting this widget in several places, the product and order pages.

The orders page, in particular, is the one that appears following a login, perfect for attracting our vendor's attention!

You should see the widget like this when you log in with a Store that do not have activated it's account.

And by click on the Activate Now button, it should redirect you directly to the Stripe page.

In order to be displayed in this way at the end of the process :

Recap

Throughout this series, we've explored the process of extending and customizing Medusa.

Leveraging Medusa's flexibility, we've enabled users/vendors (call them how you like haha) to create products, define shipping options, manage orders individually and integrate with Stripe for payouts.

While our course has been a rewarding one, it's important to recognize that we've only scratched the surface of Medusa's capabilities.

Platforms such as Amazon and Etsy offer a wide range of features and functionality to meet a variety of "business requirements", however, the knowledge and skills you've gained in this series have provided you with the foundation you need to further develop Medusa's core functionality and apply advanced concepts to your project!

Support my work

If you've enjoyed this series, or if you'd like to see other parts, feel free to buy me a coffee by clicking here, or become a sponsor of the perseides blog by clicking here

GitHub Branch

You can access the complete part's code here.

You can also have access to the storefront code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild

In this new section, we'll take a look at payments in preparation for what's to come.

What's the goal here?

In the same spirit as Orders, we're going to divide a single Payment into several for each store, or to be more transparent, we're going to create dummy payments for each store.

Let me explain.

The idea behind perseides is to create a marketplace with as little friction as possible. In fact, by creating dummy payments for each child order, we'll be able to calculate the total amount available for each seller on a specific order and we will not have to update a lot of logic. An example is the refund of an order. With this system, the refund will recalculate the child payment (which will be shown to our seller), but also act on the parent payment, which will execute actions on the PaymentProcessor.

Extend the entity

It's always the same recipe when it comes to extending core features: first, you extend the entity :

// src/models/payment.ts
import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm'

import { Payment as MedusaPayment } from '@medusajs/medusa'

@Entity()
export class Payment extends MedusaPayment {
    @Index('PaymentParentId')
    @Column({ nullable: true })
    payment_parent_id?: string

    @ManyToOne(() => Payment, (payment) => payment.children)
    @JoinColumn({ name: 'payment_parent_id', referencedColumnName: 'id' })
    parent?: Payment

    @OneToMany(() => Payment, (payment) => payment.parent)
    @JoinColumn({ name: 'id', referencedColumnName: 'payment_parent_id' })
    children?: Payment[]
}

Create the migration

Once the entity has been extended, it's time to migrate and apply our changes :

npx typeorm migration:create src/migrations/add-payment-children

// src/migrations/<TIMESTAMP>-add-payment-children.ts

// ...
    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`ALTER TABLE "payment" ADD "payment_parent_id" character varying`)
        await queryRunner.query(`CREATE INDEX "PaymentParentId" ON "payment" ("payment_parent_id")`)
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`DROP INDEX "public"."PaymentParentId"`)
        await queryRunner.query(`ALTER TABLE "payment" DROP COLUMN "payment_parent_id"`)
    }
// ...

Then we build before executing the migrations :

yarn build
npx medusa migrations run

When you refresh your database, the new column payment_parent_id should appear:

Override the OrderService.createRefund function

Another important aspect concerning refunds with these child payments is that when a refund is made on a child order, the payment used to refund must be the one the parent order (the real payment) :

// src/services/order.ts

class OrderService extends MedusaOrderService {
// ... rest previously implemented
    async createRefund(orderId: string, refundAmount: number, reason: string, note?: string, config?: { no_notification?: boolean }): Promise<Order> {
        const order = await this.retrieveWithTotals(orderId, { relations: ['payments'] })

        if (!order.order_parent_id) {
            // This means we are refunding from the parent order...
            return await super.createRefund(orderId, refundAmount, reason, note, config)
        }

        // Means the refund have occured on a child order,
        // so we need to refund from the parent order and compute the new child order amount
        return await this.atomicPhase_(async (m) => {
            const orderRepo = m.withRepository(this.orderRepository_)
            const refundRepo = m.getRepository(Refund)

            // If the refund amount is greater than the order amount, we can't refund
            if (refundAmount > order.refundable_amount) {
                throw new MedusaError(MedusaError.Types.INVALID_ARGUMENT, 'Refund amount is greater than the order amount')
            }

            // We refund from the parent order
            let parentOrder = await this.retrieve(order.order_parent_id)
            parentOrder = await super.createRefund(order.order_parent_id, refundAmount, reason, `${note}\n\nRefund from child order : ${order.id}`, config)


            // We create a refund for the child order, for future computation (refundable_amount)
            const refund = refundRepo.create({
                order_id: order.id,
                amount: refundAmount,
                reason,
                note: `${note}\n\nRefund from child order : ${order.id}`,
                payment_id: order.payments?.at(0)?.id
            })
            await refundRepo.save(refund)

            // We check if the child order payment is fully refunded
            // If it is, we can set the payment status to REFUNDED
            // Otherwise, we set the payment status to PARTIALLY_REFUNDED
            const childOrderPayment = order.payments?.at(0)

            const amountRefunded = childOrderPayment.amount_refunded + refundAmount

            const isFullyRefunded = amountRefunded === childOrderPayment.amount

            await orderRepo.update(order.id, {
                payment_status: isFullyRefunded ? PaymentStatus.REFUNDED : PaymentStatus.PARTIALLY_REFUNDED
            })

            return await this.retrieve(order.id)
        })
    }

}

In the code snippet above, we make sure to check whether the order is a parent order or a child order, in the case of a parent order, no worries, the original behavior remains the original, on the other hand, in the case where a vendor requests a refund from a child order, the refund must take place on the parent order

We also create "fake" refunds on that "fake" payment, allowing us for a easier computation of the refundable amount later on.

Override the OrderService.capturePayment function

In this case, we'll make sure that when the payment for a parent order is captured, the payments for the child orders are also captured.

When we will configure the Stripe plugin, the parent payments will be captured automatically using the medusa-payment-stripe plugin options.

But we also needs to update child order payments :

// src/services/order.ts

class OrderService extends MedusaOrderService {
// ... rest previously implemented

   /**
     * When a parent payment is captured, we capture the parent order payment but also every child order payment
     */
    async capturePayment(orderId: string): Promise<Order> {
        const order = await this.retrieveWithTotals(orderId, { relations: ['payments', 'children'] })

        if (order.order_parent_id) {
            throw new MedusaError(
                MedusaError.Types.NOT_ALLOWED,
                `Order with id ${orderId} is a child order and cannot be captured.`
            )
        }

        return await this.atomicPhase_(async (m) => {
            const orderRepo = m.withRepository(this.orderRepository_)
            const paymentRepo = m.withRepository(PaymentRepository)

            for (const child of order.children) {
                const childOrder = await orderRepo.findOne({
                    where: {
                        id: child.id
                    },
                    relations: ['payments']
                })

                if (!childOrder.payments.at(0).captured_at) {
                    await paymentRepo.update(childOrder.payments.at(0).id, {
                        captured_at: new Date()
                    })
                    await orderRepo.update(child.id, {
                        payment_status: PaymentStatus.CAPTURED
                    })
                }
            }

            return await super.capturePayment(order.id)
        })
    }

}

Update the OrderPlaced subscriber

Once our Payment entity has been modified, we can update our previously created subscriber to create a Payment for each child Order created within the subscriber.

Update your code with the following :

import {
    LineItem,
    Logger,
    OrderService,
    PaymentStatus,
    ShippingMethod,
    type SubscriberArgs,
    type SubscriberConfig
} from '@medusajs/medusa'
import ShippingOptionService from 'src/services/shipping-option'
import { EntityManager } from 'typeorm'

import { Order } from '../../models/order'
import { Product } from '../../models/product'
import { Payment } from '../../models/payment'

import ProductService from '../../services/product'


export default async function handleOrderPlaced({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
    const manager = container.resolve<EntityManager>('manager')
    const logger = container.resolve<Logger>('logger')

    await manager.transaction(async (m) => {
        const orderService: OrderService = container.resolve<OrderService>('orderService')
        const productService: ProductService = container.resolve<ProductService>('productService')
        const shippingOptionService: ShippingOptionService =
            container.resolve<ShippingOptionService>('shippingOptionService')


        const orderRepo = m.getRepository(Order)
        const lineItemRepo = m.getRepository(LineItem)
        const shippingMethodRepo = m.getRepository(ShippingMethod)
        const paymentRepo = m.getRepository(Payment)

        const orderActivity = logger.activity(`Splitting order ${data.id} into child orders...`)

        const order = await orderService.retrieveWithTotals(data.id, {
            relations: ['items', 'items.variant', 'items.variant.prices', 'cart', 'payments', 'shipping_methods'],
        })

        if (!order) {
            logger.failure(orderActivity, `OrderPlacedSubscriber | Order not found for order id ${data.id}.`)
            return
        }

        // #1 : Group Items By Store Id

        const storesWithItems = new Map<string, Order['items']>()

        for (const item of order.items) {
            const product: Product = await productService.retrieve(item.variant.product_id)
            const storeId = product.store_id

            if (!storeId) {
                logger.failure(orderActivity, `OrderPlacedSubscriber | product.store_id not found for product ${product.id}.`)
                continue
            }

            if (!storesWithItems.has(storeId)) {
                storesWithItems.set(storeId, [])
            }

            storesWithItems.get(storeId).push(item)
        }

        // #2 : For each store, create a new order with the relevant items and shipping methods
        for (const [storeId, items] of storesWithItems.entries()) {

            // #2.1 : Create a new order
            const childOrder = orderRepo.create({
                ...order,
                order_parent_id: order.id,
                store_id: storeId,
                cart_id: null,
                cart: null,
                id: null,
                shipping_methods: [],
            })

            const savedChildOrder = await orderRepo.save(childOrder)

            // #2.2 : Create a new line item for each item in the order
            let totalItemsAmount: number = 0
            for (const item of items) {
                const lineItem = lineItemRepo.create({
                    ...item,
                    order_id: savedChildOrder.id,
                    cart_id: null,
                    id: null,
                })

                await lineItemRepo.save(lineItem)


                // We compute the total order amount for the child order
                totalItemsAmount += item.total
            }

            // #2.3 : Create a new shipping method for each child order with a matching shipping option that is in the same store
            let totalShippingAmount: number = 0
            for (const shippingMethod of order.shipping_methods) {
                const shippingOption = await shippingOptionService.retrieve(shippingMethod.shipping_option_id)

                if (shippingOption.store_id !== storeId) {
                    continue
                }

                const newShippingMethod = shippingMethodRepo.create({
                    ...shippingMethod,
                    id: null,
                    cart_id: null,
                    cart: null,
                    order_id: savedChildOrder.id,
                })

                await shippingMethodRepo.save(newShippingMethod)

                totalShippingAmount += shippingMethod.total
            }

            const childPayment = paymentRepo.create({
                ...order.payments[0], // In our case, we only have one payment for the order
                payment_parent_id: order.payments[0].id,
                order_id: savedChildOrder.id,
                amount: totalItemsAmount + totalShippingAmount, // This is the total amount of the child order
                cart_id: null,
                cart: null,
                id: null,
            })

            await paymentRepo.save(childPayment)

        }

        // #3 : Capture the payment for the parent order (it will also capture the child orders)
        await orderService.withTransaction(m).capturePayment(order.id)

        logger.success(orderActivity, `Order ${data.id} has been split into ${storesWithItems.size} child orders.`)

    })

}

export const config: SubscriberConfig = {
    event: OrderService.Events.PLACED,
    context: {
        subscriberId: 'order-placed-handler',
    },
}

From now on, for each order placed, a child payment will be created and linked to a child order.

In the screenshot below, here's an example of an order that has been split into several orders.

You can see that the total amount displayed is explicitly that of the products and shipping costs linked to that specific Store only :

   /**
     * When a parent payment is captured, we capture the parent order payment but also every child order payment
     */
    async capturePayment(orderId: string): Promise<Order> {
        const order = await this.retrieveWithTotals(orderId, { relations: ['payments', 'children'] })

        if (order.order_parent_id) {
            throw new MedusaError(
                MedusaError.Types.NOT_ALLOWED,
                `Order with id ${orderId} is a child order and cannot be captured.`
            )
        }

        return await this.atomicPhase_(async (m) => {
            const orderRepo = m.withRepository(this.orderRepository_)
            const paymentRepo = m.withRepository(PaymentRepository)

            for (const child of order.children) {
                const childOrder = await orderRepo.findOne({
                    where: {
                        id: child.id
                    },
                    relations: ['payments']
                })

                if (!childOrder.payments.at(0).captured_at) {
                    await paymentRepo.update(childOrder.payments.at(0).id, {
                        captured_at: new Date()
                    })
                    await orderRepo.update(child.id, {
                        payment_status: PaymentStatus.CAPTURED
                    })
                }
            }

            return await super.capturePayment(order.id)
        })
    }

What's Next ?

In the next section, we'll be integrating Stripe and Stripe Connect, so don't forget to create your Stripe and Stripe Connect account.

GitHub Branch

You can access the complete part's code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild

Many of you have been waiting for this part, so here we're going to cover how to manage orders for each seller. Indeed, the most logical and widely used way is the one outlined by Shahed Nasserin her tutorial series that inspired perseides.

What's the goal here ?

To ensure that our vendors can process their orders independently, we're going to extend the Order entity to add some new features, for example, we will split an Order into multiple child orders, allowing a vendor to only access its order and the items they need to fulfill.

Extend the Order

Extend the Order entity

First, we'll extend the entity we're getting used to :

import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm'

import { Order as MedusaOrder } from '@medusajs/medusa'

import { Store } from './store'

@Entity()
export class Order extends MedusaOrder {
    @Index('OrderStoreId')
    @Column({ nullable: true })
    store_id?: string

    @ManyToOne(() => Store, (store) => store.orders)
    @JoinColumn({ name: 'store_id', referencedColumnName: 'id' })
    store?: Store

    @Index('OrderParentId')
    @Column({ nullable: true })
    order_parent_id?: string

    @ManyToOne(() => Order, (order) => order.children)
    @JoinColumn({ name: 'order_parent_id', referencedColumnName: 'id' })
    parent?: Order

    @OneToMany(() => Order, (order) => order.parent)
    @JoinColumn({ name: 'id', referencedColumnName: 'order_parent_id' })
    children?: Order[]
}

Here we have added :

• a store_id as on our previous entities

• a new order_parent_id column, which is nullable, allowing us to know whether an order has a parent or not

• relations that allow us to find out the parent or children of an order

Updating the Store entity

As usual, we've added a relationship that points to our Store, so we'll need to update it to add the orders property to the Store entity :

// src/models/store.ts
import { Entity, OneToMany } from 'typeorm'

import { Store as MedusaStore } from '@medusajs/medusa'

import { Product } from './product'
import { User } from './user'
import { ShippingOption } from './shipping-option'
import { ShippingProfile } from './shipping-profile'
import { Order } from './order'

@Entity()
export class Store extends MedusaStore {
    @OneToMany(() => User, (user) => user.store)
    members?: User[]

    @OneToMany(() => Product, (product) => product.store)
    products?: Product[]

    @OneToMany(() => ShippingOption, (shippingOption) => shippingOption.store)
    shippingOptions?: ShippingOption[]

    @OneToMany(() => ShippingProfile, (shippingProfile) => shippingProfile.store)
    shippingProfiles?: ShippingProfile[]

    // ✅ Our missing relation
    @OneToMany(() => Order, (order) => order.store)
    orders?: Order[]
}

Create the migration

Once the entity and repository have been extended, it's time for the migration :

npx typeorm migration:create src/migrations/add-order-store-id-and-children

We can add thoses new features by updating the up and down functions :

    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`ALTER TABLE "order" ADD "store_id" character varying`)
        await queryRunner.query(`CREATE INDEX "OrderStoreId" ON "order" ("store_id")`)

        await queryRunner.query(`ALTER TABLE "order" ADD "order_parent_id" character varying`)
        await queryRunner.query(`CREATE INDEX "OrderParentId" ON "order" ("order_parent_id")`)
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(`DROP INDEX "public"."OrderParentId"`)
        await queryRunner.query(`ALTER TABLE "order" DROP COLUMN "order_parent_id"`)

        await queryRunner.query(`DROP INDEX "public"."OrderStoreId"`)
        await queryRunner.query(`ALTER TABLE "order" DROP COLUMN "store_id"`)
    }

We can apply our changes by launching the server with yarn build and npx medusa migrations run .

Extend the OrderService

Ready to start integrating our features ? We'll make sure to only list the orders linked to a Store, and for the first time we'll also see how to prevent a Store from accessing an Order that do not belongs to it :

import { FindConfig, OrderService as MedusaOrderService, Selector } from '@medusajs/medusa'
import { Lifetime } from 'awilix'
import { MedusaError } from 'medusa-core-utils'

import type { User } from '../models/user'
import type { Order } from '../models/order'

type OrderSelector = {
    store_id?: string
} & Selector<Order>

class OrderService extends MedusaOrderService {
    static LIFE_TIME = Lifetime.TRANSIENT

    protected readonly loggedInUser_: User | null

    constructor(container, options) {
        // @ts-ignore
        super(...arguments)

        try {
            this.loggedInUser_ = container.loggedInUser
        } catch (e) {
            // avoid errors when backend first runs
        }
    }

    async list(selector: OrderSelector, config?: FindConfig<Order>): Promise<Order[]> {
        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: OrderSelector, config?: FindConfig<Order>): Promise<[Order[], 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(orderId: string, config: FindConfig<Order> = {}): Promise<Order> {

        config.relations = [...(config.relations || []), 'store']

        const order = await super.retrieve(orderId, config)

        if (order.store?.id && 
            this.loggedInUser_?.store_id && 
            order.store.id !== this.loggedInUser_.store_id) {
             throw new MedusaError(
                MedusaError.Types.NOT_FOUND,
                `Order with id ${orderId} was not found`
            )
        }

        return order
    }
}

export default OrderService

Three functions have been overrided in the above code. For the first two, if you've followed the previous sections, they simply add a WHERE condition to our SQL query to target a specific store_id if we have a logged in user with a store id.

For the retrieve function, which allows us to retrieve an order, here we retrieve the Order with its associated store (or not, in the case of a parent Order) with the original function.

And we take care to validate after we have the Order, to compare the store_id of the order with that of the logged-in user.

Create Order's subscribers

Ok so get ready, this part will be a little longer, but I assure you it's essential to your marketplace.

As I said at the beginning of this part, the idea is to split an order into several child orders, based on each store in an order.

For example, if the customer has created an order with 3 different products, all from a different store (3 different stores), we'd expect 3 different orders.

Order Placed Event

Create the Order placed subscriber

Here, I'll create a folder inside the src/subscribers folder and name it orders, so that all subscribers linked to orders will be inside.

We can now create the order-placed.ts subscriber inside that new folder :

// src/subscribers/orders/order-placed.ts

import {
    Logger,
    OrderService,
    type SubscriberArgs,
    type SubscriberConfig
} from '@medusajs/medusa'
import { EntityManager } from 'typeorm'

export default async function handleOrderPlaced({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
    const manager = container.resolve<EntityManager>('manager')
    const logger = container.resolve<Logger>('logger')

}

export const config: SubscriberConfig = {
    event: OrderService.Events.PLACED,
    context: {
        subscriberId: 'order-placed-handler',
    },
}

For the moment, we're going to keep things very simple and simply have this piece of code that we'll feed in as we go along.

By the way, it reminds me that this is the first time we're going to use the manager.

The manager will enable us to create a transaction, which will be very useful here and we have already used in the previous part quickly.

A transaction is a way to ensure that multiple database operations are executed as a single atomic unit of work. This means that either all operations succeed and are committed to the database, or if any operation fails, all operations are rolled back and the database remains unchanged (Pretty cool, right?)

Retrieve the Order placed

First, we'll retrieve the order that has just been created and intercepted by our subscriber :

// ... rest for size purposes
await manager.transaction(async (m) => {
    const orderService: OrderService = container.resolve<OrderService>('orderService')
    const productService: ProductService = container.resolve<ProductService>('productService')
    const shippingOptionService: ShippingOptionService =
        container.resolve<ShippingOptionService>('shippingOptionService')

    const orderRepo = m.getRepository(Order)
    const lineItemRepo = m.getRepository(LineItem)
    const shippingMethodRepo = m.getRepository(ShippingMethod)

    const orderActivity = logger.activity(`Splitting order ${data.id} into child orders...`)

    const order = await orderService.retrieve(data.id, {
        relations: ['items', 'items.variant', 'items.variant.prices', 'cart', 'payments', 'shipping_methods'],
    })

    if (!order) {
        logger.failure(orderActivity, `OrderPlacedSubscriber | Order not found for order id ${data.id}.`)
        return
    }
   // We have successfully retrieved the Order,
   // we'll add our next logic here.

})

// ... rest for size purposes

Grouping LineItems by Store

It's easier to group products by store so you know how many distinct stores there are, and it will make creating a child order easier :

if (!order) {
    logger.failure(orderActivity, `OrderPlacedSubscriber | Order not found for order id ${data.id}.`)
    return
}

// #1 : Group Items By Store Id

const storesWithItems = new Map<string, Order['items']>()

for (const item of order.items) {
    const product: Product = await productService.retrieve(item.variant.product_id)
    const storeId = product.store_id

    if (!storeId) {
        logger.failure(orderActivity, `OrderPlacedSubscriber | product.store_id not found for product ${product.id}.`)
        continue
    }

    if (!storesWithItems.has(storeId)) {
        storesWithItems.set(storeId, [])
    }

    storesWithItems.get(storeId).push(item)
}

Creating a child Order for each store

Just below the code above, we will begin a loop on each item in our Map to construct a child order for each of the shops, including all of the LineItems indicated above :

// #2 : For each store, create a new order with the relevant items and shipping methods
for (const [storeId, items] of storesWithItems.entries()) {

    // #2.1 : Create a new order
    const childOrder = orderRepo.create({
        ...order,
        order_parent_id: order.id,
        store_id: storeId,
        cart_id: null,
        cart: null,
        id: null,
        shipping_methods: [],
    })

    const savedChildOrder = await orderRepo.save(childOrder)

    // #2.2 : Create a new line item for each item in the order
    for (const item of items) {
        const lineItem = lineItemRepo.create({
            ...item,
            order_id: savedChildOrder.id,
            cart_id: null,
            id: null,
        })
        await lineItemRepo.save(lineItem)
    }

   // Do not close the for loop yet.

Create a ShippingMethod for each child order

Still inside the loop, we'll create a ShippingMethod for each store, so that each store can manage the progress of the delivery independently. If you don't know the difference between a ShippingMethod and a ShippingOption, I invite you to read this part of the documentation

// #2.3 : Create a new shipping method for each child order with a matching shipping option that is in the same store
for (const shippingMethod of order.shipping_methods) {
    const shippingOption = await shippingOptionService.retrieve(shippingMethod.shipping_option_id)

    if (shippingOption.store_id !== storeId) {
        continue
    }

    const newShippingMethod = shippingMethodRepo.create({
        ...shippingMethod,
        id: null,
        cart_id: null,
        cart: null,
        order_id: savedChildOrder.id,
    })
    await shippingMethodRepo.save(newShippingMethod)
}

Complete implementation

// src/subscribers/orders/order-placed.ts
import {
    LineItem,
    Logger,
    OrderService,
    ShippingMethod,
    type SubscriberArgs,
    type SubscriberConfig
} from '@medusajs/medusa'
import ShippingOptionService from 'src/services/shipping-option'
import { EntityManager } from 'typeorm'
import { Order } from '../../models/order'
import { Product } from '../../models/product'
import ProductService from '../../services/product'

export default async function handleOrderPlaced({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
    const manager = container.resolve<EntityManager>('manager')
    const logger = container.resolve<Logger>('logger')

    await manager.transaction(async (m) => {
        const orderService: OrderService = container.resolve<OrderService>('orderService')
        const productService: ProductService = container.resolve<ProductService>('productService')
        const shippingOptionService: ShippingOptionService =
            container.resolve<ShippingOptionService>('shippingOptionService')

        const orderRepo = m.getRepository(Order)
        const lineItemRepo = m.getRepository(LineItem)
        const shippingMethodRepo = m.getRepository(ShippingMethod)

        const orderActivity = logger.activity(`Splitting order ${data.id} into child orders...`)

        const order = await orderService.retrieve(data.id, {
            relations: ['items', 'items.variant', 'items.variant.prices', 'cart', 'payments', 'shipping_methods'],
        })

        if (!order) {
            logger.failure(orderActivity, `OrderPlacedSubscriber | Order not found for order id ${data.id}.`)
            return
        }

        // #1 : Group Items By Store Id

        const storesWithItems = new Map<string, Order['items']>()

        for (const item of order.items) {
            const product: Product = await productService.retrieve(item.variant.product_id)
            const storeId = product.store_id

            if (!storeId) {
                logger.failure(orderActivity, `OrderPlacedSubscriber | product.store_id not found for product ${product.id}.`)
                continue
            }

            if (!storesWithItems.has(storeId)) {
                storesWithItems.set(storeId, [])
            }

            storesWithItems.get(storeId).push(item)
        }

        // #2 : For each store, create a new order with the relevant items and shipping methods
        for (const [storeId, items] of storesWithItems.entries()) {

            // #2.1 : Create a new order
            const childOrder = orderRepo.create({
                ...order,
                order_parent_id: order.id,
                store_id: storeId,
                cart_id: null,
                cart: null,
                id: null,
                shipping_methods: [],
            })

            const savedChildOrder = await orderRepo.save(childOrder)

            // #2.2 : Create a new line item for each item in the order
            for (const item of items) {
                const lineItem = lineItemRepo.create({
                    ...item,
                    order_id: savedChildOrder.id,
                    cart_id: null,
                    id: null,
                })
                await lineItemRepo.save(lineItem)
            }

            // #2.3 : Create a new shipping method for each child order with a matching shipping option that is in the same store
            for (const shippingMethod of order.shipping_methods) {
                const shippingOption = await shippingOptionService.retrieve(shippingMethod.shipping_option_id)

                if (shippingOption.store_id !== storeId) {
                    continue
                }

                const newShippingMethod = shippingMethodRepo.create({
                    ...shippingMethod,
                    id: null,
                    cart_id: null,
                    cart: null,
                    order_id: savedChildOrder.id,
                })
                await shippingMethodRepo.save(newShippingMethod)
            }
        }

        logger.success(orderActivity, `OrderPlacedSubscriber | Order ${data.id} has been split into ${storesWithItems.size} child orders.`)
    })
}

export const config: SubscriberConfig = {
    event: OrderService.Events.PLACED,
    context: {
        subscriberId: 'order-placed-handler',
    },
}

Perfect! We now have a way of splitting an Order into several child Orders!

However, we still need to listen to other Order events.

Order Updated Event

Here, we're going to intercept an order whenever it has been updated. The idea is to be able to update the parent Order according to the status of its children :

import {
    FulfillmentStatus,
    OrderStatus,
    PaymentStatus,
    type SubscriberArgs,
    type SubscriberConfig,
} from '@medusajs/medusa'
import type OrderRepository from '@medusajs/medusa/dist/repositories/order'

import type { Order } from '../../models/order'
import OrderService from '../../services/order'


export default async function handleOrderUpdated({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
    const orderService: OrderService = container.resolve('orderService')
    const orderRepo: typeof OrderRepository = container.resolve('orderRepository')

    const order = await orderService.retrieve(data.id)

    if (!order.order_parent_id) {
        return
    }

    const parentOrder = await orderService.retrieve(order.order_parent_id, {
        relations: ['children'],
    })

    const status = await getStatusFromChildren(parentOrder)

    if (status !== parentOrder.status) {
        switch (status) {
            case OrderStatus.CANCELED:
                await orderService.cancel(parentOrder.id)
            case OrderStatus.ARCHIVED:
                await orderService.archive(parentOrder.id)
            case OrderStatus.COMPLETED:
                await orderService.completeOrder(parentOrder.id)
            default:
                parentOrder.status = status
                parentOrder.fulfillment_status = (status === 'completed'
                    ? FulfillmentStatus.SHIPPED
                    : status) as unknown as FulfillmentStatus
                parentOrder.payment_status = (status === 'completed') ? PaymentStatus.CAPTURED : status as unknown as PaymentStatus
                await orderRepo.save(parentOrder)
        }
    }
}

async function getStatusFromChildren(order: Order) {
    if (!order.children) {
        return order.status
    }

    let statuses = order.children.map((child) => child.status)
    //remove duplicate statuses
    statuses = [...new Set(statuses)]

    if (statuses.length === 1) {
        return statuses[0]
    }

    statuses = statuses.filter((status) => status !== OrderStatus.CANCELED && status !== OrderStatus.ARCHIVED)

    if (!statuses.length) {
        //all child orders are archived or canceled
        return OrderStatus.CANCELED
    }

    if (statuses.length === 1) {
        return statuses[0]
    }

    //check if any order requires action
    const hasRequiresAction = statuses.some((status) => status === OrderStatus.REQUIRES_ACTION)

    if (hasRequiresAction) {
        return OrderStatus.REQUIRES_ACTION
    }

    //since more than one status is left and we filtered out canceled, archived,
    //and requires action statuses, only pending and complete left. So, return pending
    return OrderStatus.PENDING
}

export const config: SubscriberConfig = {
    event: [
        OrderService.Events.UPDATED,
        OrderService.Events.FULFILLMENT_CREATED,
        OrderService.Events.FULFILLMENT_CANCELED,
        OrderService.Events.GIFT_CARD_CREATED,
        OrderService.Events.ITEMS_RETURNED,
        OrderService.Events.PAYMENT_CAPTURED,
        OrderService.Events.PAYMENT_CAPTURE_FAILED,
        OrderService.Events.REFUND_CREATED,
        OrderService.Events.REFUND_FAILED,
        OrderService.Events.RETURN_ACTION_REQUIRED,
        OrderService.Events.RETURN_REQUESTED,
        OrderService.Events.SHIPMENT_CREATED,
        OrderService.Events.SWAP_CREATED,
    ],
    context: {
        subscriberId: 'order-updated-handler',
    },
}

Create a subscriber that will update the child order's status

Medusa doesn't implement any predefined conditions for setting the status of an order to completed, in our example below.

In our example below, we'll set the status of an order to “complete” when :

• This order has a payment_status of completed.

• This order has a fulfillment_status of completed.

• We'll also make sure that the order in question hasn't been canceled, archived or already completed

import {
    type SubscriberConfig,
    type SubscriberArgs,
    FulfillmentStatus,
    PaymentStatus,
    OrderStatus,
} from '@medusajs/medusa'
import OrderService from '../../services/order'
import type { Order } from '../../models/order'

export default async function handleOrderUpdated({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
    const orderService: OrderService = container.resolve('orderService')

    const order = await orderService.retrieve(data.id)

    if (!order.order_parent_id) {
        return
    }

    const parentOrder = await orderService.retrieve(order.order_parent_id, {
        relations: ['children'],
    })

    await updateStatusOfChildren(parentOrder, orderService)
}

/**
 * This function is executed when a child order is updated.
 * It checks if the child order has a payment status of "captured" and a fulfillment status of "shipped".
 * If both conditions are met, it updates the child order's status to "complete", allowing a parent order to be marked as "complete" too.
 */
async function updateStatusOfChildren(order: Order, orderService: OrderService) {
    if (!order.children) {
        return
    }

    const ordersToComplete = order.children
        .filter((child) => child.payment_status === PaymentStatus.CAPTURED)
        .filter((child) => child.fulfillment_status === FulfillmentStatus.SHIPPED)
        .filter(
            (child) =>
                child.status !== OrderStatus.CANCELED &&
                child.status !== OrderStatus.ARCHIVED &&
                child.status !== OrderStatus.COMPLETED,
        )

    if (ordersToComplete.length === 0) {
        return
    }

    for (const order of ordersToComplete) {
        await orderService.completeOrder(order.id)
    }
}

export const config: SubscriberConfig = {
    event: [
        OrderService.Events.UPDATED,
        OrderService.Events.FULFILLMENT_CREATED,
        OrderService.Events.FULFILLMENT_CANCELED,
        OrderService.Events.GIFT_CARD_CREATED,
        OrderService.Events.ITEMS_RETURNED,
        OrderService.Events.PAYMENT_CAPTURED,
        OrderService.Events.PAYMENT_CAPTURE_FAILED,
        OrderService.Events.REFUND_CREATED,
        OrderService.Events.REFUND_FAILED,
        OrderService.Events.RETURN_ACTION_REQUIRED,
        OrderService.Events.RETURN_REQUESTED,
        OrderService.Events.SHIPMENT_CREATED,
        OrderService.Events.SWAP_CREATED,
    ],
    context: {
        subscriberId: 'child-order-updated-handler',
    },
}

And now you've successfully implemented the splitting of one order into several for each Store! Granted, this part of the program was rather heavy and involved a lot of different concepts, so don't hesitate to take the time to reread the code and try to understand the integrated flow.

If you have any questions, you can send me a DM on Twitter/X or on the official Medusa Discord!

What's Next ?

The next part will be a little special, we'll be looking at Payments entity, and we'll be extending it, but this will be more of an exercise for you, of course the solution will also be included, but it might be nice to practice customizing an entity on your own.

Common Issues

I have types errors!

Do not forget to update you index.d.ts file created earlier, at this point, and what we have used, you should have an index.d.ts file that looks like this :

// src/index.d.ts
import type { Product } from './models/product'
import type { ShippingProfile } from './models/shipping-profile'
import type { ShippingOption } from './models/shipping-option' 
import type { Order } from './models/shipping-order' 

declare module '@medusajs/medusa/dist/models/product' {
    interface Product {
        store_id?: string
        store?: Store
    }
}

declare module '@medusajs/medusa/dist/models/shipping-profile' {
    interface ShippingProfile {
        store_id?: string
        store?: Store
    }
}

declare module '@medusajs/medusa/dist/models/shipping-option' {
    interface ShippingOption {
        store_id?: string
        store?: Store
    }
}

declare module '@medusajs/medusa/dist/models/order' {
    interface Order {
        store_id?: string
        store?: Store
        order_parent_id?: string
        parent?: Order
        children?: Order[]
    }
}

GitHub Branch

You can access the complete part's code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild

Now that we've extended the ShippingOption and ShippingProfile entities, we can start integrating new features into our services.

What's the goal here ?

The aim of this part is to override various functions of the ShippingOption and ShippingProfile services, so that vendors can only access their own shipping options/profiles, and create a shipping option/profile for their store only.

We'll also look at the concept of loaders, to create a default ShippingProfile for each store.

ShippingOptionService

Extend the service

Let's start by creating the ShippingOptionService file :

// src/services/shipping-option.ts
import { ShippingOptionService as MedusaShippingOptionService } from '@medusajs/medusa'
import { Lifetime } from 'awilix'

import type { User } from '../models/user'

class ShippingOptionService extends MedusaShippingOptionService {
    static LIFE_TIME = Lifetime.TRANSIENT
    protected readonly loggedInUser_: User | null

    constructor(container, options) {
        // @ts-ignore
        super(...arguments)

        try {
            this.loggedInUser_ = container.loggedInUser
        } catch (e) {
            // avoid errors when backend first runs
        }
    }

}

export default ShippingOptionService

Override the ShippingOptionService.list function

We will now override the ShippingOptionService.list function and the ShippingOptionService.listAndCount function:

import { ShippingOptionService as MedusaShippingOptionService } from '@medusajs/medusa'
import { Lifetime } from 'awilix'

import { FindConfig, Selector } from '@medusajs/medusa'

import type { ShippingOption } from '../models/shipping-option'
import type { User } from '../models/user'

type ShippingOptionSelector = {
    store_id?: string
} & Selector<ShippingOption>

class ShippingOptionService extends MedusaShippingOptionService {   
     // ... rest

    async list(
        selector?: ShippingOptionSelector & { q?: string },
        config?: FindConfig<ShippingOption>,
    ): Promise<ShippingOption[]> {
        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?: ShippingOptionSelector & { q?: string },
        config?: FindConfig<ShippingOption>,
    ): Promise<[ShippingOption[], 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)
    }
}

Override the ShippingOptionService.create function

We also override the ShippingOptionService.create function and the CreateShippingOptionInput type to allow for a store_id property :

// ... other imports
import { CreateShippingOptionInput as MedusaCreateShippingOptionInput } from '@medusajs/medusa/dist/types/shipping-options'

type CreateShippingOptionInput = {
    store_id?: string
} & MedusaCreateShippingOptionInput

class ShippingOptionService extends MedusaShippingOptionService {
    // ... rest 
   async create(data: CreateShippingOptionInput): Promise<ShippingOption> {
        if (!data.store_id && this.loggedInUser_?.store_id) {
            data.store_id = this.loggedInUser_.store_id
        }

        return await super.create(data)
    }
}

export default ShippingOptionService

Override the ShippingOptionService.validateCartOption

A final function to be overrided is the validateCartOption function, which validates a ShippingOption for a Cart before saving it in the Cart. Here, we're going to make sure that a chosen shipping option, has one or more products that belongs to the same store :

class ShippingOptionService extends MedusaShippingOptionService {
    // ... rest
    async validateCartOption(option: ShippingOption, cart: Cart): Promise<ShippingOption | null> {
        const validatedOption = await super.validateCartOption(option, cart)

        const hasAnItemFromStore = cart.items.some((item) => item.variant.product.store_id === option.store_id)

        if (!hasAnItemFromStore) {
            throw new MedusaError(MedusaError.Types.NOT_ALLOWED, 'Shipping option does not exist for store')
        }

        return validatedOption
    }
}

export default ShippingOptionService

ShippingProfileService

Extend the service

Before launching our server and starting to create ShippingOption, we need to extend ShippingProfileService :

import {
    ShippingProfileService as MedusaShippingProfileService
} from '@medusajs/medusa'
import { Lifetime } from 'awilix'

import type { User } from '../models/user'


class ShippingProfileService extends MedusaShippingProfileService {
    static LIFE_TIME = Lifetime.TRANSIENT
    protected readonly loggedInUser_: User | null

    constructor(container, options) {
        // @ts-ignore
        super(...arguments)

        try {
            this.loggedInUser_ = container.loggedInUser
        } catch (e) {
            // avoid errors when backend first runs
        }
    }
}

export default ShippingProfileService

Override the ShippingProfileService.list

By overriding this function, we can ensure that only the ShippingProfiles of the connected user's store are listed:

import {
    FindConfig,
    ShippingProfileService as MedusaShippingProfileService,
    Selector
} from '@medusajs/medusa'
import { Lifetime } from 'awilix'

import { ShippingProfile } from '../models/shipping-profile'
import type { User } from '../models/user'

type ShippingProfileSelector = {
    store_id?: string
} & Selector<ShippingProfile>

class ShippingProfileService extends MedusaShippingProfileService {
    static LIFE_TIME = Lifetime.TRANSIENT
    protected readonly loggedInUser_: User | null

    constructor(container, options) {
        // @ts-ignore
        super(...arguments)

        try {
            this.loggedInUser_ = container.loggedInUser
        } catch (e) {
            //  avoid errors when backend first runs
        }
    }

    async list(
        selector: ShippingProfileSelector = {},
        config: FindConfig<ShippingProfile> = {}
    ): Promise<ShippingProfile[]> {
        if (!selector.store_id && this.loggedInUser_?.store_id){
            selector.store_id = this.loggedInUser_.store_id
        }

        config.relations = [...(config.relations ?? []), 'store'];

        config.select = [
            ...(config.select ?? []),
            'id',
            'name',
            'created_at',
            'deleted_at',
            'updated_at',
            'type',
            'store_id',
            'metadata',
        ];

        return await super.list(selector, config);
    }
}

export default ShippingProfileService

Override the ShippingProfileService.create

When creating a ShippingProfile, if a user is logged in, we can assign its store_id :

// ...imports
import { CreateShippingProfile as MedusaCreateShippingProfile } from '@medusajs/medusa/dist/types/shipping-profile'

type CreateShippingProfile = {
    store_id?: string
} & MedusaCreateShippingProfile

class ShippingProfileService extends MedusaShippingProfileService { 
    // ...rest
    async create(profile: CreateShippingProfile): Promise<ShippingProfile> {
        if (!profile.store_id && this.loggedInUser_?.store_id) {
            profile.store_id = this.loggedInUser_.store_id
        }

        return await super.create(profile)
    }
}

export default ShippingProfileService

Override the ShippingProfile.retrieveDefault function

Overriding this function allows for new created products being linked to the store's shipping profile, this is useful for the storefront, since it will fetch Cart options depending on the shipping profile of the current products in the Cart :

    async retrieveDefault(): Promise<ShippingProfile> {
        if (this.loggedInUser_?.store_id) {
            return this.shippingProfileRepository_.findOne({
                where: {
                    type: ShippingProfileType.CUSTOM,
                    store_id: this.loggedInUser_.store_id
                }
            })
        }

        return super.retrieveDefault()
    }

Create the ShippingProfile.createDefaultForStore function

This function will later allow us to create default ShippingProfile for our stores:

class ShippingProfileService extends MedusaShippingProfileService { 
    // ...rest
    async createDefaultForStore(storeId: string): Promise<ShippingProfile> {
        return await this.atomicPhase_(async (manager) => {
            const profileRepository = manager.withRepository(this.shippingProfileRepository_)

            const profile = await profileRepository.findOne({ where: { store_id: storeId } })
            if (profile) {
                return profile
            }

            const toCreate: Partial<ShippingProfile> = {
                type: ShippingProfileType.CUSTOM,
                name: 'Default Shipping Profile',
                store_id: storeId,
            }

            const created = profileRepository.create(toCreate)

            return await profileRepository.save(created)
        })
    }
}

export default ShippingProfileService

Here we have wrapped our process into a transaction (this.atomicPhase_) , so that in the case of an error throwed when creating a user (for example, an email already in use), no event is sent and it will rollback changes.

Create your first loader

Before launching our server and creating ShippingOption, we're going to make sure that each store has its own default ShippingProfile.

To do this, we're going to make sure that, when the server starts, shipping profiles are created automatically for each new store.

In our case, we're going to create a file in the src/loaders/create-defaults-shipping-profiles.ts folder :

import { Logger, MedusaContainer } from '@medusajs/medusa'
import type StoreRepository from '@medusajs/medusa/dist/repositories/store'
import type ShippingProfileService from '../services/shipping-profile'

export default async function (container: MedusaContainer): Promise<void> {
    const shippingProfileService = container.resolve<ShippingProfileService>('shippingProfileService')
    const storeRepo = container.resolve<typeof StoreRepository>('storeRepository')
    const logger = container.resolve<Logger>('logger')

    const allStores = await storeRepo.find({
        select: ['id'],
    })

    if (!allStores.length) {
        return
    }

    const allShippingProfiles = await shippingProfileService.list()

    for (const store of allStores) {
        const storeId = store.id

        // For each store, we check that there is a default shipping profile
        // if not, we create one
        if (!allShippingProfiles.find((profile) => profile.store_id === storeId)) {
            const promise = logger.activity(`Creating default shipping profile for store ${storeId}...`)
            await shippingProfileService.createDefaultForStore(storeId)
            logger.success(promise, `Created default shipping profile for store ${storeId}!`)
        }
    }
}

Perfect, but this will only work when we start our server, so we'll also make sure that when a store is created, a default shipping profile is created, so that nothing needs to be restarted.

Update the StoreService

We're going to update our StoreService so that it exposes a kind of enum that will represent events. These events will be emitted and listened to afterwards:

// src/services/store.ts

// ... imports

class StoreService extends MedusaStoreService {
    static LIFE_TIME = Lifetime.TRANSIENT
    protected readonly loggedInUser_: User | null

    static Events = {
        CREATED: 'store.created', // ✅ We had a static property to access easily events
    }

   // ... rest

}

export default StoreService

Update the UserService

Now we can use this event name in our UserService when creating a new store:

// src/services/user.ts

// ...imports
class UserService extends MedusaUserService {
    // ... rest

    async create(
        user: CreateUserInput,
        password: string
    ): Promise<User> {
        return await this.atomicPhase_(async (m) => {
            const storeRepo = m.withRepository(this.storeRepository_)

            if (!user.store_id) {
                let newStore = storeRepo.create()
                newStore = await storeRepo.save(newStore)
                user.store_id = newStore.id
            }

            const savedUser = await super.create(user, password)

            this.eventBus_.emit(StoreService.Events.CREATED, { id: user.store_id })

            return savedUser
        })
    }
}

export default UserService

Create your first subscriber

Once our event is ready to emit, all we need to do is create a Subscriber that will listen and execute code when it receives the event. In this case, we'll create a ShippingProfile each time a new store is created:

// src/subscribers/store-created.ts
import type { Logger, SubscriberArgs, SubscriberConfig } from '@medusajs/medusa'

import ShippingProfileService from '../services/shipping-profile'
import StoreService from '../services/store'

export default async function handleStoreCreated({
    data,
    eventName,
    container,
    pluginOptions,
}: SubscriberArgs<Record<string, string>>) {

    const shippingProfileService = container.resolve<ShippingProfileService>("shippingProfileService")
    const logger = container.resolve<Logger>("logger")

    const promise = logger.activity(`Creating default shipping profile for store ${data.id}`)

    await shippingProfileService.createDefaultForStore(data.id).catch(e => {
        logger.error(e, `Error creating default shipping profile for store ${data.id}`)
        throw e
    })

    logger.success(promise, `Default shipping profile for store ${data.id} created`)
}

export const config: SubscriberConfig = {
    event: StoreService.Events.CREATED,
    context: {
        subscriberId: 'store-created-handler',
    },
}

The ShippingProfile is now inserted each time a new store is created, without having to restart our server and wait for our loader to process :

We can now take the time to test the Admin UI with two separate accounts, for example.

In the screenshot below, we can see that each one sees only its own Shipping options, linked to their own Shipping Profile under the hood :

What's Next ?

In the next part, we'll look into Orders, specifically how to ensure that each vendor can handle their own order. This will be an opportunity to use all we've learned in the previous parts, as well as to reuse the Subscriber notion from that current part!

GitHub Branch

You can access the complete part's code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild

In the last part, we were able to customize the behavior of products on our marketplace, so vendors/users can now create products specific to their store and, of course, see only their own products.

What's the goal here ?

In this part, we will extend ShippingOption to make them relevant to a store. In fact, each vendor must be able to input its own shipping options, giving the customer choices for each vendors.

We'll also extend the behavior of ShippingProfile to link them to a store too, because the shopping cart currently allows for multiple shipping methods, but the current implementation only allows for one per shipping profile, so we'll create one by default for each store, allowing for multiple shipping methods for a single cart.

ShippingOption

Extend the ShippingOption entity

As with our previous entities, we want a ShippingOption to be linked to a Store :

// src/models/shipping-option.ts
import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm'

import { ShippingOption as MedusaShippingOption } from '@medusajs/medusa'

import { Store } from './store'

@Entity()
export class ShippingOption extends MedusaShippingOption {
    @Index('ShippingOptionStoreId')
    @Column({ nullable: true })
    store_id?: string

    @ManyToOne(() => Store, (store) => store.shippingOptions)
    @JoinColumn({ name: 'store_id', referencedColumnName: 'id' })
    store?: Store
}

Update the Store entity

Adding a ManyToOne relationship above also means updating the Store model:

// src/models/store.ts
import { Entity, OneToMany } from 'typeorm'

import { Store as MedusaStore } from '@medusajs/medusa'

import { Product } from './product'
import { User } from './user'
import { ShippingOption } from './shipping-option'

@Entity()
export class Store extends MedusaStore {
    @OneToMany(() => User, (user) => user.store)
    members?: User[]

    @OneToMany(() => Product, (product) => product.store)
    products?: Product[]

    @OneToMany(() => ShippingOption, (shippingOption) => shippingOption.store)
    shippingOptions?: ShippingOption[]
}

Create the ShippingOption migration

Once the entity and repository have been extended, we can now create our :

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

Now that the migration file has been created, we can replace the up and down functions with these:

public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`ALTER TABLE "shipping_option" ADD "store_id" character varying`)
    await queryRunner.query(`CREATE INDEX "ShippingOptionStoreId" ON "shipping_option" ("store_id")`)
}

public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`DROP INDEX "public"."ShippingOptionStoreId"`)
    await queryRunner.query(`ALTER TABLE "shipping_option" DROP COLUMN "store_id"`)
}

You can now build your server using the yarn build command and then run the npx medusa migrations run command, as for our previous migrations to make the changes in your database :

ShippingProfile

Extend the ShippingProfile entity

Once the ShippingOption entity has been fully extended, we also need to extend the ShippingProfile entity, almost like copying and pasting what we've done above.

In the same way :

import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm'

import { ShippingProfile as MedusaShippingProfile } from '@medusajs/medusa'

import { Store } from './store'

@Entity()
export class ShippingProfile extends MedusaShippingProfile {
    @Index('ShippingProfileStoreId')
    @Column({ nullable: true })
    store_id?: string

    @ManyToOne(() => Store, (store) => store.shippingProfiles)
    @JoinColumn({ name: 'store_id', referencedColumnName: 'id' })
    store?: Store
}

Update the Store entity

We update our Store entity to add the new shippingProfiles property :

// src/models/store.ts
import { Column, Entity, OneToMany } from 'typeorm'

import { Store as MedusaStore } from '@medusajs/medusa'

import { User } from './user'
import { Product } from './product'
import { ShippingOption } from './shipping-option'
import { ShippingProfile } from './shipping-profile'

@Entity()
export class Store extends MedusaStore {
    @OneToMany(() => User, (user) => user.store)
    members?: User[]

    @OneToMany(() => Product, (product) => product.store)
    products?: Product[]

    @OneToMany(() => ShippingOption, (shippingOption) => shippingOption.store)
    shippingOptions?: ShippingOption[]

    @OneToMany(() => ShippingProfile, (shippingProfile) => shippingProfile.store)
    shippingProfiles?: ShippingProfile[]
}

Create the ShippingProfile migration

We can now create the migration file for the ShippingProfile migration to apply our changes to the database :

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

// src/migrations/<TIME>-add-shipping-profile-store-id.ts

// ...
public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`ALTER TABLE "shipping_profile" ADD "store_id" character varying`)
    await queryRunner.query(`CREATE INDEX "ShippingProfileStoreId" ON "shipping_profile" ("store_id")`)
}

public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`DROP INDEX "public"."ShippingProfileStoreId"`)
    await queryRunner.query(`ALTER TABLE "shipping_profile" DROP COLUMN "store_id"`)
}
// ...

By executing this new migration file, we should see the changes occurs in our database schema :

What's Next ?

Next, we'll look at the two services: ShippingProfileService and ShippingOptionService, and how/what we can override some of their functions. We'll use the same reasoning as the ProductService, where we made sure to fetch only the products associated with a Store or tie a new product to a specific store.

GitHub Branch

You can access the complete part's code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild

Now that our vendors have access to their store, I can tell they are getting bored. Indeed, without any things to sell, our back office is useless, therefore we're spending this time expanding the product concept and adding a decent bit of customization.

What is the goal here ?

The benefit of this section of the tutorial is that it allows you to apply everything you've learned in prior sections.

First, we will:

• Create a new file in themodelsfolder, that will extend the core entity with new properties

• Create a new migration using the TypeORM CLI

• Create a new file in theservicesfolder that will initially only include our basic changes (LIFE_TIME,this.loggedInUser_...)

Once these steps are completed, we'll get down to the essential of adding these features :

• Create a product related to a vendor

• List the products of a vendor

Extend the Product entity

Here is where we define the new schema for the product table. In fact, we want to associate a product with a store, therefore we use the same reasoning as the User table we extended earlier :

// src/models/product.ts
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
}

A relationship with the Store implies an update of the previously extended Store model:

// src/models/store.ts
import { Entity, OneToMany } from 'typeorm'

import { Store as MedusaStore } from '@medusajs/medusa'

import { Product } from './product'
import { User } from './user'

@Entity()
export class Store extends MedusaStore {
    @OneToMany(() => User, (user) => user.store)
    members?: User[]

    @OneToMany(() => Product, (product) => product.store)
    products?: Product[]
}

Create a Migration

Once the preceding parts are completed, we may create a migration to notify the database of certain changes; the command is as follows :

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

Once the migration file has been created, we can update the up and down functions like this :

// src/migrations/...-add-product-store-id.ts

// ...
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"`)
}
// ...

Perfect, now we can run build our server and run the migrations, after that, the database we should see the new column in the product table :

Adding new features

Create a Product for a Store

To create a Product tied to a Store, we'll start by extending the ProductService and overriding the create function to force the logged-in user's store_id into the product before inserting it. However, you will see type problems with the input type expected on the method, therefore we will need to expand the type to add our new store_id property :

// src/services/product.ts

import type { CreateProductInput as MedusaCreateProductInput } from '@medusajs/medusa/dist/types/product'
import { ProductService as MedusaProductService } from '@medusajs/medusa'
import { Lifetime } from 'awilix'

import type { User } from '../models/user'
import type { Product } from '../models/product'

// We override the type definition so it will not throw TS errors in the `create` method
type CreateProductInput = {
    store_id?: string
} & MedusaCreateProductInput

class ProductService extends MedusaProductService {
    static LIFE_TIME = Lifetime.TRANSIENT
    protected readonly loggedInUser_: User | null

    constructor(container) {
        // @ts-ignore
        super(...arguments)

        try {
            this.loggedInUser_ = container.loggedInUser
        } catch (e) {
            // avoid errors when backend first runs
        }
    }

    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

Okay, at our level here, we can be sure that a User who is logged in AND has a µ store_id must be able to create a product for its store.

On the other hand, when a User wants to retrieve products, there are currently no constraints preventing him from seeing ONLY its store's products, let's implement this feature.

List Products for a Store

ProductService.listAndCount is the function that retrieves products used in the back-office, therefore we'll alter it to include the logged-in user's store_id to retrieve only his products. However, the selector of this function does not know the store_id property at all, so we will expand the selector to make it aware of that new property :

// ... rest
import { ProductSelector as MedusaProductSelector } from '@medusajs/medusa/dist/types/product'

type ProductSelector = {
    store_id?: string
} & MedusaProductSelector

class ProductService extends MedusaProductService {
    // ... rest

    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')

        const products = await super.listAndCount(selector, config)
        return products
    }
}

You can now try it on the Admin UI or directly with the API, and you should get the behavior expected.

What's Next ?

We now have the foundation; vendors can access the admin UI and create/list products associated with their store; in the next phase, we will extend entities to allow each store to create its own shipping options.

Common Issues

A product handle must be unique

The product.handle might create an issue in the long term when creating a product for a store, as it's supposed to be unique. You can for example either add a prefix or suffix containing the store_id to avoid any problems :

// src/services/product.ts
class ProductService extends MedusaProductService {
    // ... rest
    async create(productObject: CreateProductInput): Promise<Product> {
        if (!productObject.store_id && this.loggedInUser_?.store_id) {
            productObject.store_id = this.loggedInUser_.store_id

            // This will generate a handle for the product based on the title and store_id
            // e.g. "sunglasses-01HXVYMJF9DW..."
            const title = productObject.title.normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/\s+/g, '-').toLowerCase()
            const store_id = this.loggedInUser_.store_id.replace("store_", "")

            productObject.handle = `${title}-${store_id}`
        }

        return await super.create(productObject)
    }
}

I want to retrieve products from a specific store only from my storefront

For that you'll need to create a loader, that will extend the default /store/products relations and allowed fields.

First you'll need to create a new loader in the /src/loaders/ directory :

// src/loaders/extend-store-products.ts
export default async function (): Promise<void> {
    const module = await import('@medusajs/medusa/dist/api/routes/store/products/index')

    Object.assign(module, {
        ...module,
        defaultStoreProductsRelations: [...module.defaultStoreProductsRelations, 'store'],
        defaultStoreProductsFields: [...module.defaultStoreProductsFields, 'store_id'],
        allowedStoreProductsRelations: [...module.allowedStoreProductsRelations, 'store'],
        allowedStoreProductsFields: [...module.allowedStoreProductsFields, 'store_id'],
    })
}

Then we'll extend the validators of the /store/products API route, the goal here is to be able to add a query parameter /store/products?store_id=<STORE_ID> , and the default Medusa validator for that API is not aware of the new property we wants to add.

Next step, is to create a file in the /src/api/ folder, named specifically index.ts .

// src/api/index.ts
import { registerOverriddenValidators } from "@medusajs/medusa"

// Here we are importing the original Medusa validator as an alias :
import {
   StoreGetProductsParams as MedusaStoreGetProductsParams,
} from "@medusajs/medusa/dist/api/routes/store/products/list-products"
import { IsString, IsOptional } from "class-validator"

// Here we add the new allowed property `store_id` :
class StoreGetProductsParams extends MedusaStoreGetProductsParams {
   @IsString()
   @IsOptional() // Optional of course
   store_id?: string
}

// The following function will replace the original validator by the new one.
registerOverriddenValidators(StoreGetProductsParams)

Now you can successfully retrieve all products from a specific store like this.

curl http://localhost:9000/store/products?store_id=<YOUR_STORE_ID>

I have TypeScript errors !

In the same way that we have notified the database of new changes thanks to migrations, we will have to do the same with our packages, which are not aware of new properties.

Remember to declare your types according to your needs. In our case, we only need the following types :

// src/index.d.ts
import type { Product } from './models/product'
import type { Store } from './models/store'

declare module '@medusajs/medusa/dist/models/product' {
    interface Product {
        store_id?: string
        store?: Store
    }
}

GitHub Branch

You can access the complete part's code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild

In this part of our Medusa.js marketplace journey, we'll continue building on the groundwork we established in the previous sections. This time, our focus will be on extending the StoreService and ProductService to ensure a seamless user experience.

What is the goal here ?

The core objective here is to guarantee that when a user logs into the admin ui, they can seamlessly access their own store based on their store_id. This level of personalization is crucial for providing a tailored experience within our marketplace. As you've noted, the approach involves extending the existing services to achieve this functionality. Let's dive into the details.

Extend the Store Service

We'll create a new file in the services folder, named store.ts, where we'll extend the StoreService to override the retrieve function.

// src/services/store.ts
import { type FindConfig, StoreService as MedusaStoreService, buildQuery } from "@medusajs/medusa"
import { Lifetime } from 'awilix'

import type { User } from "../models/user"
import type { Store } from "../models/store"

class StoreService extends MedusaStoreService {
    static LIFE_TIME = Lifetime.TRANSIENT
    protected readonly loggedInUser_: User | null

    constructor(container, options) {
        // @ts-ignore
        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_ || !this.loggedInUser_.store_id) {
                // In case there is no loggedInUser or no store_id, 
                // we just use the original function 
                // that retrieves the default store
                return await super.retrieve(config)
            }

            const storeRepo = this.activeManager_.withRepository(this.storeRepository_)

            const query = buildQuery<Partial<Store>, Store>(
                {
                    id: this.loggedInUser_.store_id,
                },
                {
                    ...config,
                    relations: [...(config?.relations || []), 'members'],
                },
            )

            return await storeRepo.findOne(query)
        }
}

export default StoreService

In this extended StoreService, we override the retrieve method to check if the logged-in user is defined and have a store_id associated with their account. If so, we use that store_id to retrieve that specific store information. Otherwise, we fall back to the default behavior of the StoreService (which will just use the default store created by the Medusa core loaders)

What's Next ?

Well done, now that the right store is displayed, we will extend the products in the next part!

GitHub Branch

You can access the complete part's code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild

Last year, I embarked on my first (client) project using Medusa.js to build a marketplace. Since then, Medusa has undergone significant improvements, and I believe it's beneficial to share insights on constructing a marketplace with the latest versions.

A marketplace is...

A marketplace, conceptually, is a platform where multiple vendors can sell various products to numerous customers. One key aspect I've learned is that typically, the marketplace retains funds until certain conditions are met (e.g an order has been delivered to the customer), after which payouts are made to vendors, including fees.

In this blog series, we'll delve into building a specific type of marketplace—a clothing marketplace where anyone can register and start selling their products.

While we won't cover every detail, the aim is to equip you with the knowledge to customize Medusa.js for creating a simple yet functional marketplace.
You'll likely need to manage many aspects independently, but this guide will prepare you well.

It's important to note that not every marketplace will be identical, and the provided examples might not exactly match the marketplace you envision.

Let's start by following the recipe detailed in the Medusa documentation. The documentation covers various concepts and sometimes includes actual code implementations.

This will be a heavy first part, as it will condense certain points from the official documentation, but I promise that the rest of the parts will be lighter in terms of text.

Before we start...

As we progress through this series, we will be enhancing and altering some of Medusa's fundamental logic and functionality.

However, the ability to use the sales channels feature flag may be impossible upon the design approach taken.

The current design of the Cart system, particularly its integration with sales channels, poses a challenge. It is structured in a way that precludes the possibility of associating multiple sales channels with a single Cart.

If you wish to leverage the sales channels feature, you have the flexibility to modify the Cart system or develop a similar mechanism to fully capitalize on its capabilities.

You'll learn how to disable the sales_channels feature flag by clicking here.

Following the recipe

The first part of our journey involves extending entities. The documentation guides us on how to begin this process, starting with the concept of a User linked to a Store (where the User acts as a vendor, it's distinct from a Customer).

Extending the User entity

Here’s how we can start extending the User entity:

// src/models/user.ts
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
}

Extending the Store entity

Next, we extend the Store entity to include a new property representing our OneToMany relationship, which is necessary to avoid type errors in the previously extended User model :

// src/models/store.ts
import { Entity, OneToMany } from 'typeorm';
import { Store as MedusaStore } from '@medusajs/medusa';
import { User } from './user';

@Entity()
export class Store extends MedusaStore {
    @OneToMany(() => User, (user) => user.store)
    members?: User[];
}

Our First Migration

After extending the User and Store entities, we proceed with a database migration to reflect these changes in the schema. We continue following the recipe by executing the following command in our terminal:

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

Here's how we replace the up and down functions in our new migration with the ones provided in the docs :

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"`
    );
}

How to apply migrations ?

To apply these migrations, we build our server and run the CLI command:

yarn build
npx medusa migrations run

If we check our database now, we should see a new store_id column in the user table!

Our First Middleware

We have just set up the foundation for our marketplace by extending the User and Store entities and creating the necessary migrations. Now, we'll dive deeper into customizing the data management functionalities using middleware and service extensions.

Registering a Logged-in User / Middleware

Medusa.js provides a way to create middleware that can be applied to specific routes. In the context of our marketplace, we want to ensure that the logged-in user's information is available throughout our application, especially when retrieving data. Let's create a new middleware that will register the logged-in user in the request scope:

// src/api/middlewares.ts
import { 
  authenticate,
} from "@medusajs/medusa"
import type { 
  MedusaNextFunction, 
  MedusaRequest, 
  MedusaResponse,
  MiddlewaresConfig, 
  User, 
  UserService,
} from "@medusajs/medusa"

const registerLoggedInUser = async (
  req: MedusaRequest, 
  res: MedusaResponse, 
  next: MedusaNextFunction
) => {
  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()
}

export const config: MiddlewaresConfig = {
  routes: [
    {
      matcher: /^\/admin\/(?!auth|analytics-config|users\/reset-password|users\/password-token|invites\/accept).*/,
      middlewares: [authenticate(), registerLoggedInUser],
    },
  ],
}

In this middleware, we first check if there is a logged-in user in the request. If so, we retrieve the user's information using the userService.

We then register the loggedInUser value in the request scope, which can be accessed by other services and components.

Extending the User Service

Next, let's extend the UserService to automatically create a new store when a new user is registered. This will ensure that every user has a store associated with their account, which is a key requirement for our marketplace :

// src/services/user.ts
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 type StoreRepository from "@medusajs/medusa/dist/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-ignore
        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 extended UserService, we override the create method to check if the user has a store_id associated with their account. If not, we create a new store and associate it with the user's account before creating the new user.

Let's run our server and try to create a new User, we can use Postman or HTTPie to make a POST request to /admin/users when logged-in.

Let's try with a simple payload like this one :

// [POST] /admin/users
{
    "email":"john@doe.com",
    "password":"1234"
}

You should get a server's response like this one :

{
   "user": {
      "email":"john@doe.com",
      "store_id":"store_01HX6NFWW7R7306VHQ1PSP8YN7", 
      // ✅ ☝️ Just what we wanted!
      "id":"usr_01HX6NFX8G78KHB6KD3MDS69VH",
      "role":"member",
      "first_name":null,
      "last_name":null,
      "api_token":null,
      "metadata":null,
      "created_at":"2024-05-06T09:59:19.1182",
      "updated_at":"2024-05-06T09:59:19.118Z",
      "deleted_at":null
   }
}

Now, whenever we create a new User a new Store is associated to it !

What's Next ?

And this is where this first part of the series ends, as the recipe gives us a few more concepts, such as associating a store_id with the creation of a product etc., before moving on to the events/subscribers.

We're not going to tackle events just yet, but rather continue to focus on service management and how to extend them so as to have everything nicely tied up to a vendor.

Common Issues

I have CORS errors since I've added middlewares

If you have any CORS errors when accessing the Admin UI, this might solves your issue

import { authenticate, type MiddlewaresConfig } from '@medusajs/medusa'
import { parseCorsOrigins } from 'medusa-core-utils'
import * as cors from 'cors' // ⚠️ Make sure you import it like this

import registerLoggedInUser from './middlewares/register-logged-in-user'

export const config: MiddlewaresConfig = {
    routes: [
        {
            matcher: /^\/admin\/(?!auth|analytics-config|users\/reset-password|users\/password-token|invites\/accept).*/,
            middlewares: [
                cors.default({ credentials: true, origin: parseCorsOrigins(process.env.ADMIN_CORS ?? '') }),
                authenticate(),
                registerLoggedInUser,
            ],
        },
    ],
}

MyloggedInUserisundefinedornull

If you have this issue and are sure that you are logged in before making a request, please update your LIFE_TIME services to TRANSIENT, it should fix the issues :

// An example with the UserService extended earlier
class UserService extends MedusaUserService {
  static LIFE_TIME = Lifetime.TRANSIENT
  // ...
}

GitHub Branch

You can access the complete part's code here.

Contact

You can contact me on Discord and X with the same username : @adevinwild