medusa-subscribers

Medusa v2 Subscribers and Scheduled Jobs

Before writing code

Fetch live docs:

1. Fetch https://docs.medusajs.com/learn/fundamentals/events-and-subscribers for subscriber overview
2. Web-search site:docs.medusajs.com subscriber handler function for handler API
3. Web-search site:docs.medusajs.com scheduled jobs cron for scheduled job patterns
4. Web-search site:docs.medusajs.com event module redis for event bus configuration
5. Web-search site:docs.medusajs.com built-in events list for available event names

Subscriber Concept

Subscribers react to events emitted by Medusa workflows and services:

• Asynchronous by default -- do not block the emitting operation
• Registered as files in src/subscribers/
• Each file exports a default handler function and a config object
• Events follow a naming convention: {entity}.{action} (e.g., product.created)

Subscriber File Structure

src/subscribers/
├── product-created.ts     # Reacts to product.created
├── order-placed.ts        # Reacts to order.placed
└── customer-registered.ts # Reacts to customer.created

Each file is auto-discovered -- no manual registration required.

Subscriber Handler Pattern

// src/subscribers/product-created.ts
// Fetch live docs for SubscriberArgs and SubscriberConfig types
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"

export default async function productCreatedHandler(
  { event, container }: SubscriberArgs<{ id: string }>) {
  // event.data.id contains the entity ID — fetch live docs for payload shapes
}

Config Export

// Fetch live docs for SubscriberConfig options
export const config: SubscriberConfig = {
  event: "product.created",
}

Event Naming Conventions

Domain	Event Examples
Products	product.created, product.updated, product.deleted
Orders	order.placed, order.canceled, order.completed
Customers	customer.created, customer.updated
Cart	cart.created, cart.updated
Fulfillment	fulfillment.created, fulfillment.canceled
Payment	payment.captured, payment.refunded
Inventory	inventory-item.created
Auth	invite.created, invite.accepted