Discord Notifications

@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 Copy to clipboard{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. Copy to clipboard{total}, Copy to clipboard{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

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

Setup

1. Add to Copy to clipboardmedusa-config.ts

123456789101112
import { DiscordNotificationOptions } from "@sam-ael/medusa-plugin-discord/modules/discord-notification"

plugins: [
  {
    resolve: "@sam-ael/medusa-plugin-discord",
    options: {
      // Global fallback bot name. Can also be set via env var (see below).
      // Per-mapping bot names set in the Admin UI take priority over this.
      defaultBotName: process.env.DISCORD_DEFAULT_BOT_NAME || "Discord Bot",
    } satisfies DiscordNotificationOptions,
  },
],

2. Set Environment Variables (Optional)

12
# .env
DISCORD_DEFAULT_BOT_NAME="My Store Bot"

3. Run Migrations

1
npx medusa db:migrate

Admin UI

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

Webhook Mapping Fields

Field Required Description Event Trigger ✅ Which Medusa event fires this webhook Discord Webhook URL ✅ Full Discord webhook URL Channel Label ❌ Friendly label (e.g. Copy to clipboard#orders) — display only Bot Name ❌ Override the bot's display name for this channel. Falls back to Copy to clipboarddefaultBotName plugin option → Copy to clipboard"Discord Bot" Custom Message Template ❌ Discord Markdown template. Leave blank for default rich embed. Enabled ✅ Toggle to activate/deactivate without deleting

Message Lifecycle (In-Place Editing)

The plugin stores the Discord Copy to clipboardmessage_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.

12345
order.placed           → POST new message  → message_id saved to DB
order.fulfillment_created → PATCH same message  → status updated to "Fulfillment Created 📦"
fulfillment.shipment_created → PATCH same message → status + tracking links shown 🚚
order.completed        → PATCH same message → status "Completed ✅" (green)
order.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 Copy to clipboardmessage_id.

Supported Events

Event Description Copy to clipboardorder.placed New order placed Copy to clipboardorder.fulfillment_created Fulfillment created for an order Copy to clipboardfulfillment.shipment_created Shipment created with tracking info Copy to clipboardorder.completed Order marked as completed Copy to clipboardorder.canceled Order canceled Copy to clipboardorder.updated Order updated Copy to clipboardcustomer.created New customer registered Copy to clipboardcustomer.updated Customer profile updated

Template Placeholders

Order Events

Placeholder Description Copy to clipboard{id} Order ID Copy to clipboard{display_id} Human-readable order number Copy to clipboard{status} Order status Copy to clipboard{total} Order total (formatted as decimal) Copy to clipboard{subtotal} Subtotal (formatted as decimal) Copy to clipboard{currency_code} Currency code (e.g. Copy to clipboardusd) Copy to clipboard{email} Customer email Copy to clipboard{payment_status} Payment status Copy to clipboard{fulfillment_status} Fulfillment status Copy to clipboard{shipment_status} Copy to clipboardPending, Copy to clipboardFulfillment Created, or Copy to clipboardShipped Copy to clipboard{tracking_numbers} Comma-separated tracking numbers Copy to clipboard{tracking_links} Tracking numbers as clickable Discord markdown links Copy to clipboard{shipping_address.first_name} Shipping first name Copy to clipboard{shipping_address.last_name} Shipping last name Copy to clipboard{shipping_address.city} Shipping city Copy to clipboard{customer.email} Customer account email

Customer Events

Placeholder Description Copy to clipboard{id} Customer ID Copy to clipboard{email} Email address Copy to clipboard{first_name} First name Copy to clipboard{last_name} Last name Copy to clipboard{phone} Phone number

Plugin Options

12345678
type DiscordNotificationOptions = {
  /**
   * Global fallback bot username shown in Discord when no
   * per-mapping bot_name is configured in the Admin UI.
   * Defaults to "Discord Bot".
   */
  defaultBotName?: string
}

Admin API Reference

Method Endpoint Description Copy to clipboardGET Copy to clipboard/admin/discord/mappings List all webhook mappings Copy to clipboardPOST Copy to clipboard/admin/discord/mappings Create a new webhook mapping Copy to clipboardPOST Copy to clipboard/admin/discord/mappings/:id Update a webhook mapping Copy to clipboardDELETE Copy to clipboard/admin/discord/mappings/:id Delete a webhook mapping Copy to clipboardPOST Copy to clipboard/admin/discord/test Send a test notification using mock data

Mapping Payload

12345678
{
  "event_name": "order.placed",
  "webhook_url": "https://discord.com/api/webhooks/...",
  "channel_name": "#orders",
  "bot_name": "Enchauntee Sales Bot",
  "is_active": true,
  "message_template": "📦 New order **#{display_id}** from **{email}** — **{total} {currency_code}**"
}

Development

12
yarn typecheck
yarn build

License

MIT