Product

Announcing Improved Subscriber API

Nov 27, 2023 by

Kasper Kristensen and Oliver Juhl

Our improved Subscriber API allows developers to run logic in response to events in Medusa using simple JavaScript functions.

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.

Subscribers

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.

123456789101112131415
// 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
/subscribers
```
control the behavior of your event handlers. The default export is a function with the logic to run, and the
```
Copy to clipboard
config
```
export specifies the event that logic should be run in response to
The handler accepts an argument of type
```
Copy to clipboard
SubscriberArgs
```
. 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
event

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.

1234567891011121314
// 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: [
        ProductService.Events.CREATED,
        ProductService.Events.UPDATED,
        ProductService.Events.DELETED
    ]
}

By updating the

Copy to clipboard
event

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