Discord

@sam-ael/medusa-plugin-discord

A Discord webhook notification plugin for Medusa v2. Route store events to your Discord channels with rich embed cards that automatically update in-place as order status changes — from placed → fulfilled → shipped → completed or canceled.

Features

• Live Message Editing — One message per order, edited in place as status changes. No channel spam.
• Shipment & Tracking — Displays tracking numbers and links as clickable Discord markdown when an order is shipped.
• Premium Rich Embeds — Beautiful default embed cards with color-coded status badges (🟡 Pending → 🚚 Shipped → 🟢 Completed → 🔴 Canceled).
• Custom Markdown Templates — Write your own message templates using Discord Markdown with {placeholders}.
• Configurable Bot Name — Set a global fallback bot name via plugin config or env var, and override per-channel from the Admin UI.
• Interactive Admin UI — Manage all webhook mappings and templates directly from the Medusa Admin panel settings.
• Placeholder Sidebar — Click a field (e.g. {total}, {tracking_links}) to insert it at your cursor in the template editor.
• Price Formatting — Automatically converts price fields from Medusa's integer cents to human-readable decimals.
• Multiple Event Triggers — Supports order, fulfillment, shipment, and customer events.

Installation

yarn add @sam-ael/medusa-plugin-discord

Setup

1. Add to medusa-config.ts

1import { DiscordNotificationOptions } from "@sam-ael/medusa-plugin-discord/modules/discord-notification"
2
3plugins: [
4  {
5    resolve: "@sam-ael/medusa-plugin-discord",
6    options: {
7      // Global fallback bot name. Can also be set via env var (see below).
8      // Per-mapping bot names set in the Admin UI take priority over this.
9      defaultBotName: process.env.DISCORD_DEFAULT_BOT_NAME || "Discord Bot",
10    } satisfies DiscordNotificationOptions,
11  },
12],

2. Set Environment Variables (Optional)

1# .env
2DISCORD_DEFAULT_BOT_NAME="My Store Bot"

3. Run Migrations

npx medusa db:migrate

Admin UI

Navigate to Settings → Discord Notifications in the Medusa Admin panel.

Webhook Mapping Fields

Message Lifecycle (In-Place Editing)

The plugin stores the Discord message_id returned when an order notification is first posted. All subsequent events for the same order edit that same message rather than posting new ones.

1order.placed           → POST new message  → message_id saved to DB
2order.fulfillment_created → PATCH same message  → status updated to "Fulfillment Created 📦"
3fulfillment.shipment_created → PATCH same message → status + tracking links shown 🚚
4order.completed        → PATCH same message → status "Completed ✅" (green)
5order.canceled         → PATCH same message → status "Canceled 🔴" (red)

If the original Discord message is manually deleted, the plugin automatically posts a fresh message and saves the new message_id.

Supported Events

Template Placeholders

Order Events

Customer Events

Plugin Options

1type DiscordNotificationOptions = {
2  /**
3   * Global fallback bot username shown in Discord when no
4   * per-mapping bot_name is configured in the Admin UI.
5   * Defaults to "Discord Bot".
6   */
7  defaultBotName?: string
8}

Admin API Reference

Mapping Payload

1{
2  "event_name": "order.placed",
3  "webhook_url": "https://discord.com/api/webhooks/...",
4  "channel_name": "#orders",
5  "bot_name": "Enchauntee Sales Bot",
6  "is_active": true,
7  "message_template": "📦 New order **#{display_id}** from **{email}** — **{total} {currency_code}**"
8}

Development

1yarn typecheck
2yarn build

License

MIT