Announcing Improved Subscriber API

Nov 27, 2023 by

undefined avatar

Kasper Kristensen

undefined avatar
undefined avatar

Oliver Juhl

undefined avatar

Kasper Kristensen and Oliver Juhl

Our improved Subscriber API allows developers to run logic in response to events in Medusa using simple JavaScript functions.
altText of the image
We care deeply about developer experience across all our products. Our primitives and tooling allow developers to effortlessly build digital commerce applications at record speed.
Today, we are excited to announce a massive update to our Subscriber API that significantly improves the developer experience of a core concept in Medusa’s customization toolbox.


Services in Medusa emit events whenever actions like creating and updating records occur. Subscribers in Medusa provide a way for developers to run asynchronous logic in response to these events. This could include syncing a product to an external service when it is updated in Medusa or applying a special discount when a set of specific products is added to a cart.
With our updated API, you can create subscribers using a pattern similar to how you build API Routes.
// src/subscribers/order-placed.ts
export default async function ({ data, container }) {
const { id } = data
const slackService = container.resolve("slackService")
const orderService = container.resolve("orderService")
const order = await orderService.retrieve(id)
await slackService.sendNotis({ data: order })
export const config: SubscriberConfig = {
event: OrderService.Events.PLACED,
Example of a Subscriber
The example above illustrates a few key points of the updated Subscriber API:
  • Exports from files in
    Copy to clipboard
    control the behavior of your event handlers. The default export is a function with the logic to run, and the
    Copy to clipboard
    export specifies the event that logic should be run in response to
  • The handler accepts an argument of type
    Copy to clipboard
    . This can be de-structured to access the event data and the Medusa container.
In the example above, we register a handler that is run every time the product updated event is triggered.
The new approach to registering subscribers also comes with the benefit of making it easier than ever to set up a handler for multiple events. The
Copy to clipboard
field in the config accepts either a single event or a list of events. Continuing with the above example, it would be possible to update the handler to update the external system when a product is created, updated, and deleted.
// src/subscribers/product-sync.ts
import { syncProductsWorkflow } from "../workflows"
export default async function ({ data, eventName, container }) {
await syncProductsWorkflow.run({ input: data })
export const config: SubscriberConfig = {
event: [
By updating the
Copy to clipboard
field and adding a few additional lines of code, the handler can now process all relevant events. This keeps the external system synchronized with Medusa.

What is next?

We are excited to hear your thoughts about our new Subscriber API. If you have any feedback or experience issues, don’t hesitate to post on our GitHub Issues board or GitHub Discussions. To check other of our recent releases, check out our Medusa Recap page.
You can also track our progress on X and in our changelog.

Share this post

Try Medusa

Spin up your environment in a few minutes.