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 </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

npm install medusa-plugin-richpanel

Configure

Add the plugin to the plugins array in medusa-config.ts:

1module.exports = defineConfig({
2  // ...
3  plugins: [
4    {
5      resolve: "medusa-plugin-richpanel",
6      options: {
7        appClientId: process.env.RICHPANEL_APP_CLIENT_ID!,
8        webhookSecret: process.env.RICHPANEL_WEBHOOK_SECRET!,
9      },
10    },
11  ],
12})

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

1RICHPANEL_APP_CLIENT_ID=<your app client id>
2RICHPANEL_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 .env and restart. Rotating the secret later is then an env change plus a redeploy, with no code edit.

Options

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 {event, data, timestamp} to Richpanel, signed with x-richpanel-signature (HMAC-SHA256 of the request body using your webhookSecret):

• order.placed, order.updated, order.canceled, order.completed
• order.fulfillment_created, shipment.created, delivery.created
• order.return_requested, order.return_received
• customer.created, customer.updated
• payment.captured, payment.refunded

Payloads contain IDs only (as emitted by Medusa); Richpanel fetches full records through your store's Admin API connection. For shipment.created, delivery.created, payment.captured and payment.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 order_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 missing option(s) ... — appClientId or webhookSecret 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 [medusa-plugin-richpanel] warnings. HTTP 401 means the webhookSecret doesn't match what Richpanel generated; re-copy it. Network errors usually mean your backend can't reach connector-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