Richpanel

medusa-plugin-richpanel

Connect your Medusa store to Richpanel. The plugin pushes order, customer, fulfillment, return and payment events from your Medusa backend to Richpanel, so your support team (and Richpanel's AI agent) sees order context next to every conversation.

Requires Medusa v2.4 or later.

Setup (end to end)

The whole integration is driven from Richpanel — this plugin is step 2. Start in the Richpanel app; each step below says where it happens.

1. Connect in Richpanel. Go to app.richpanel.com → Settings → Integrations → Medusa, click Connect, enter your Medusa backend URL and Admin API key, and pick the brand. Richpanel generates your App client ID and a webhook secret (shown once — copy it).
2. Install this plugin for real-time sync. In your Medusa backend, install and configure the plugin with those two values (see Install and Configure), then redeploy/restart. New orders, customers, fulfillments, returns and payments stream to Richpanel as they happen.
3. Add live chat to your storefront. Copy the widget snippet shown on the Richpanel Medusa page and paste it before Copy to clipboard</head> in your storefront app, then redeploy the storefront. The Richpanel chat widget then appears for your shoppers.
4. Backfill your history (one-time). Back on the Richpanel Medusa page, open Historical import, choose a date range, and click Start import to pull past orders and customers so agents have full history from day one.

Steps 1, 3 and 4 happen in the Richpanel app and your storefront; step 2 is this plugin.

Install

1
npm install medusa-plugin-richpanel

Configure

Add the plugin to the Copy to clipboardplugins array in Copy to clipboardmedusa-config.ts:

123456789101112
module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: "medusa-plugin-richpanel",
      options: {
        appClientId: process.env.RICHPANEL_APP_CLIENT_ID!,
        webhookSecret: process.env.RICHPANEL_WEBHOOK_SECRET!,
      },
    },
  ],
})

Set both values as environment variables on your backend — keep them out of source control:

12
RICHPANEL_APP_CLIENT_ID=<your app client id>
RICHPANEL_WEBHOOK_SECRET=<your webhook secret>

On Medusa Cloud, add them under Settings → Environment Variables (mark the webhook secret as sensitive) and redeploy — variable changes only apply after a redeploy. Self-hosted, put them in your backend's Copy to clipboard.env and restart. Rotating the secret later is then an env change plus a redeploy, with no code edit.

Options

Option Required Description Copy to clipboardappClientId Yes The connector's app client ID, generated by Richpanel when you add the Medusa connector. Shown on the connect screen (Settings → Connectors → Medusa). Copy to clipboardwebhookSecret Yes Shared secret used to sign every event (HMAC-SHA256). Generated by Richpanel on the connect screen.

Redeploy (Medusa Cloud) or restart (self-hosted) your backend after adding the plugin. Open the Richpanel page in the Medusa admin sidebar to confirm the connection status.

What it sends

On each of these events, the plugin POSTs Copy to clipboard{event, data, timestamp} to Richpanel, signed with Copy to clipboardx-richpanel-signature (HMAC-SHA256 of the request body using your Copy to clipboardwebhookSecret):

• Copy to clipboardorder.placed, Copy to clipboardorder.updated, Copy to clipboardorder.canceled, Copy to clipboardorder.completed
• Copy to clipboardorder.fulfillment_created, Copy to clipboardshipment.created, Copy to clipboarddelivery.created
• Copy to clipboardorder.return_requested, Copy to clipboardorder.return_received
• Copy to clipboardcustomer.created, Copy to clipboardcustomer.updated
• Copy to clipboardpayment.captured, Copy to clipboardpayment.refunded

Payloads contain IDs only (as emitted by Medusa); Richpanel fetches full records through your store's Admin API connection. For Copy to clipboardshipment.created, Copy to clipboarddelivery.created, Copy to clipboardpayment.captured and Copy to clipboardpayment.refunded — whose Medusa payloads carry only a fulfillment/payment id — the plugin resolves the owning order via Medusa's module links and adds it to the payload as Copy to clipboardorder_id. Delivery is fire-and-forget with 3 retries (1s / 5s / 25s backoff, 10s timeout per attempt) and never blocks or fails your store's event loop.

Troubleshooting

• Admin page shows "Not configured" / log warns Copy to clipboardmissing option(s) ... — Copy to clipboardappClientId or Copy to clipboardwebhookSecret is missing from the plugin options. Copy both from the Richpanel connect screen. The plugin never crashes the server for this; it just stops sending until configured.
• Orders don't appear in Richpanel — check your Medusa server logs for Copy to clipboard[medusa-plugin-richpanel] warnings. Copy to clipboardHTTP 401 means the Copy to clipboardwebhookSecret doesn't match what Richpanel generated; re-copy it. Network errors usually mean your backend can't reach Copy to clipboardconnector-service.richpanel.com (check egress rules).
• Events are delayed — Medusa events ride your Redis event bus; make sure a Redis event module is configured in production (the local in-memory bus drops events across restarts). There is no periodic reconciliation: if events were missed, run a historical import from the Medusa settings page in Richpanel to backfill.

License

MIT