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

Fetch live docs for the complete event list -- events are added and renamed across Medusa releases.

Subscribing to Multiple Events

A single subscriber can listen to multiple events:

// Fetch live docs for multi-event config
export const config: SubscriberConfig = {
  event: ["product.created", "product.updated"],
}

The handler receives the event name in event.name to distinguish which event triggered it.

Event Payload

The data shape varies per event. Typically contains the entity ID(s) affected.

Event Module Configuration

Redis Event Module Setup

// In medusa-config.ts modules array
// Fetch live docs for Redis event module configuration
{
  resolve: "@medusajs/medusa/event-bus-redis",
  options: { redisUrl: process.env.REDIS_URL },
}

In production, always use the Redis event module to ensure events are delivered across multiple server instances.

Scheduled Jobs

Scheduled jobs run on a cron schedule, independent of events:

Job File Structure

src/jobs/
├── daily-sync.ts          # Daily data synchronization
└── cleanup-expired.ts     # Periodic cleanup

Scheduled Job Skeleton

// src/jobs/daily-sync.ts
// Fetch live docs for MedusaContainer type
import type { MedusaContainer } from "@medusajs/framework"

export default async function dailySyncJob(container: MedusaContainer) {
  const service = container.resolve("my-module")
  // Fetch live docs for job handler API
}

Job Config Export

// Fetch live docs for cron expression format
export const config = {
  name: "daily-sync",
  schedule: "0 0 * * *", // Midnight daily (cron syntax)
}

Common Cron Patterns

Worker Mode and Jobs

In production, run a dedicated worker instance to handle subscribers and scheduled jobs separately from HTTP traffic.

Emitting Custom Events

Custom events can be emitted from workflows using the emitEventStep:

// Inside a workflow
// Fetch live docs for emitEventStep import
import { emitEventStep } from "@medusajs/medusa/core-flows"

emitEventStep({ eventName: "custom.event", data: { id: "123" } })

Best Practices

• Keep subscribers lightweight -- offload heavy work to workflows
• Use descriptive file names matching the event they handle
• Always type the event payload generic: SubscriberArgs<{ id: string }>
• Use the Redis event module in production for reliability across instances
• Do not perform synchronous, blocking operations in subscribers
• Use scheduled jobs for periodic tasks -- do not poll from subscribers
• Resolve services from the container, never import directly

Fetch the Medusa subscriber and events documentation for exact event names, payload shapes, and Redis event module configuration before implementing.