Plugin
VMS Guru connector for Medusa v2 — syncs orders, products and shipment tracking so packing videos link back to the right order.
VMS Guru for Medusa
Record a video of every parcel you pack, and have it link itself to the right order automatically.
When a customer says "the box was empty" or "this isn't what I ordered", you pull up the video of that exact parcel being packed and sealed.
What you get
- Every order syncs to VMS Guru automatically — no exports, no spreadsheets
- Videos match themselves to orders using the courier tracking number your packer already scans
- Watch the video from inside Medusa — it appears right on the order page
- Send the video to the customer to settle a dispute in one message
Free to use with a VMS Guru account.
Getting started
There are two steps. The first needs whoever looks after your Medusa server; the second is yours and takes about a minute.
Step 1 — Install (one time, needs your developer)
Why a developer? Medusa runs on your own server, so plugins are installed by editing configuration files rather than clicking Install like on Shopify. It's a five-minute job. Forward this section to whoever manages your store.
Install the package:
Add both entries to (the module is separate from the plugin — Medusa needs both):
Set your VMS Guru address in :
Then run the database migration and restart:
npx medusa db:migrateStep 2 — Connect to VMS Guru (that's you, no technical knowledge needed)
- Open your Medusa admin
- Go to Settings → VMS Guru in the sidebar
- Click Connect with VMS Guru
- A new tab opens — log in to your VMS Guru account
- Click Authorize & Connect
- You'll land back on a "Connected" page. Close the tab and return to Medusa
- Click Sync now once, to send your existing products and recent orders
That's it. You'll see Connected with your account name, and orders start flowing from the next one placed.
Using it day to day
You don't have to do anything else. Here's what happens on its own:
| When you… | VMS Guru… |
|---|---|
| Receive an order | Adds it to your order list |
| Add or edit a product | Keeps your SKU list current |
| Create a shipment with a tracking number | Links that tracking number to the order |
| Pack and record the parcel | Matches the video to the order automatically |
The tracking number is what ties it all together. Your packer scans the number on the courier label while recording, and VMS Guru matches that recording to the order carrying the same number. So make sure shipments are created in Medusa with a tracking number — that's the one thing that matters.
Watching a packing video
In Medusa: open any order. If a video exists, a Packing video panel appears on the right with the video, the tracking number and when it was recorded.
In VMS Guru: your dashboard shows all orders, videos and daily stats.
If something isn't working
"Not connected" even though I authorised Return to the Medusa tab and refresh. If it still says not connected, the link may have expired — connection links are valid for 10 minutes. Just click Connect with VMS Guru again.
The connect tab shows an error page Your Medusa server needs to be reachable from your browser. If it isn't (a local or firewalled setup), use the manual option: on the VMS Guru settings page click "Backend not reachable from your browser?", then paste an API key generated in your VMS Guru dashboard.
No Packing video panel on the order The panel only appears once VMS Guru has that order. Check the order shows up in your VMS Guru dashboard — if not, click Sync now on the settings page.
Panel says "No recording linked to this tracking number yet" VMS Guru has the order but no video for it. Either the parcel wasn't recorded, or the number scanned while recording doesn't match the tracking number on the shipment in Medusa.
Orders stopped syncing Open Settings → VMS Guru. If a red box shows a sync problem, it usually means the connection was reset from the VMS Guru side — click Disconnect and connect again.
Still stuck? Contact VMS Guru support with your store URL and the order number.
Settings reference
| Variable | What it's for |
|---|---|
| Your VMS Guru address. Set this — the built-in default points at a VMS Guru development server. | |
| Your Medusa server's public address. Used to bring you back after authorising. |
No plugin are needed — your connection is set up through the admin, not in config files.
Technical reference (for developers)
How syncing works
| Medusa event | Sent to VMS Guru |
|---|---|
| Records the fulfillment → order link, syncs tracking if present | |
| — stamps | |
| / |
carries only a fulfillment id, not an order id. fires earlier and carries both, so the plugin records that pair in and reads it back when the shipment arrives — avoiding a scan over the order table.
Endpoints added
| Method | Path | Auth |
|---|---|---|
| / | admin | |
| admin | ||
| admin | ||
| admin | ||
| admin | ||
| admin | ||
| state token |
Security
- sits outside because it's reached by a cross-site browser redirect carrying no admin session. It's guarded by a single-use, 10-minute minted by the authenticated and compared in constant time.
- The API key never reaches the browser. Stats and order lookups are proxied through admin routes.
- Sync failures never break Medusa — subscriber paths log, record the error on the connection, and swallow it.
Development
Migrations are hand-written. does not work on Windows: it globs with a ed pattern, so the pattern contains backslashes that glob treats as escapes — it matches nothing, writes no files, and still logs . It also needs a reachable Postgres. After changing a model, update the migration by hand or regenerate on macOS/Linux.
Note also that Medusa's generator emits , which is not in 's map and fails to resolve at both typecheck and runtime. This plugin imports from instead.
Version notes
The order widget uses zone . If it doesn't appear, check the injection-zone reference for your Medusa version.
Licence
Free to use with a VMS Guru account. Not open source — redistribution and derivative works are not permitted. See LICENSE.