How to Handle Events in Medusa Using Subscribers

Medusa is an open source ecommerce platform with plenty of features that boost the ecommerce experience for merchants while providing a great developer experience.

As a headless commerce platform, Medusa’s server architecture is composed of a few components that have different purposes and usages.

This article in particular focuses on Subscribers, what’s their purpose, and how they can be used to handle events in Medusa.

In Medusa, there are events that are emitted when a certain action occurs. For example, if a customer places an order, the 

Copy to clipboard
order.placed

 event is emitted with the order data.

These events are designed to allow other parts of the platform or third-party integrations to listen to them and take action accordingly.

Subscribers register handlers for an events and allows you to perform an action when that event occurs. For example, if you want to send your customer an email when they place an order, then you can listen to the 

Copy to clipboard
order.placed

 event and send the email when the event is emitted.

Natively in Medusa there are subscribers to handle different events. However, you can also create your own custom subscribers.

Custom subscribers reside in your project's 

Copy to clipboard
src/subscribers

 directory. Files here should export classes, which will be treated as subscribers by Medusa. By convention, the class name should end with 

Copy to clipboard
Subscriber

 and the file name should be the camel-case version of the class name without 

Copy to clipboard
Subscriber

. For example, the 

Copy to clipboard
WelcomeSubscriber

 class is in the file 

Copy to clipboard
src/subscribers/welcome.js

.

Whenever an event is emitted, the subscriber’s registered handler method is executed. The handler method receives as a parameter an object that holds data related to the event. For example, if an order is placed the 

Copy to clipboard
order.placed

 event will be emitted and all the handlers will receive the order id in the parameter object.

Medusa's event system works by pushing data to a Queue that each handler then gets notified of. The queuing system is based on Redis and you will therefore need to make sure that Redis is installed and configured for your Medusa project.

Then, you need to set your Redis URL in your Medusa server. By default, the Redis URL is 

Copy to clipboard
redis://localhost:6379

. If you use a different one, set the following environment variable in 

Copy to clipboard
.env

:

1
REDIS_URL=<YOUR_REDIS_URL>

After that, in 

Copy to clipboard
medusa-config.js

, you’ll need to comment out the following line:

123456
module.exports = {
  projectConfig: {
    redis_url: REDIS_URL, //this line is commented out
    ...
  }
}

After that, you are able to listen to events on your server.

After creating the file under 

Copy to clipboard
src/subscribers

, in the constructor of your subscriber, you should listen to events using 

Copy to clipboard
eventBusService.subscribe

 , where 

Copy to clipboard
eventBusService

 is a service injected into your subscriber’s constructor.

The

Copy to clipboard
eventBusService.subscribe

method takes an event name as its first parameter, and a callback function as its second parameter. This callback will be executed when the event is fired.

For example, here is the 

Copy to clipboard
OrderNotifierSubscriber

 class which is created in 

Copy to clipboard
src/subscribers/orderNotifier.js

:

1234567891011
class OrderNotifierSubscriber {
  constructor({ eventBusService }) {
    eventBusService.subscribe("order.placed", this.handleOrder);
  }

  handleOrder = async (data) => {
    console.log("New Order: " + data.id)
  };
}

export default OrderNotifierSubscriber;

This subscriber will register the method 

Copy to clipboard
handleOrder

 as one of the handlers of the 

Copy to clipboard
order.placed

 event. The method 

Copy to clipboard
handleOrder

 will be executed every time an order is placed, and it will receive the order ID in the 

Copy to clipboard
data

 parameter. You can then use the order’s details to perform any kind of task you need.

The 

Copy to clipboard
data

 object will not contain other order data. Only the ID of the order. You can retrieve the order information using the 

Copy to clipboard
orderService

.

You can access any service through the dependencies injected to your subscriber’s constructor.

For example:

12345
constructor({ productService, eventBusService }) {
    this.productService = productService;

    eventBusService.subscribe("order.placed", this.handleOrder);
}

You can then use 

Copy to clipboard
this.productService

 anywhere in your subscriber’s methods.

Subscribers are just one part of Medusa’s architecture. Here are some documentation that can guide you into doing more with Medusa:

Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.