VMS Guru

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:

1
npm install @vmsguru/medusa-plugin

Add both entries to Copy to clipboardmedusa-config.ts (the module is separate from the plugin — Medusa needs both):

12345678
export default defineConfig({
  plugins: [
    { resolve: "@vmsguru/medusa-plugin", options: {} },
  ],
  modules: [
    { resolve: "@vmsguru/medusa-plugin/modules/vmsguru" },
  ],
})

Set your VMS Guru address in Copy to clipboard.env:

12
VMSGURU_BACKEND_URL=https://admin.vms-guru.in
MEDUSA_BACKEND_URL=https://your-store-backend.com

Then run the database migration and restart:

1
npx medusa db:migrate

Step 2 — Connect to VMS Guru (that's you, no technical knowledge needed)

1. Open your Medusa admin
2. Go to Settings → VMS Guru in the sidebar
3. Click Connect with VMS Guru
4. A new tab opens — log in to your VMS Guru account
5. Click Authorize & Connect
6. You'll land back on a "Connected" page. Close the tab and return to Medusa
7. 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 Copy to clipboardVMSGURU_BACKEND_URL Your VMS Guru address. Set this — the built-in default points at a VMS Guru development server. Copy to clipboardMEDUSA_BACKEND_URL Your Medusa server's public address. Used to bring you back after authorising.

No plugin Copy to clipboardoptions 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 Copy to clipboardorder.placed Copy to clipboardPOST /api/medusa/orders Copy to clipboardorder.updated Copy to clipboardPOST /api/medusa/orders Copy to clipboardorder.fulfillment_created Records the fulfillment → order link, syncs tracking if present Copy to clipboardshipment.created Copy to clipboardPOST /api/medusa/fulfillments — stamps Copy to clipboardfwd_awb Copy to clipboardproduct.created / Copy to clipboardproduct.updated Copy to clipboardPOST /api/medusa/products

Copy to clipboardshipment.created carries only a fulfillment id, not an order id. Copy to clipboardorder.fulfillment_created fires earlier and carries both, so the plugin records that pair in Copy to clipboardvmsguru_fulfillment_link and reads it back when the shipment arrives — avoiding a scan over the order table.

Endpoints added

Method Path Auth Copy to clipboardGET / Copy to clipboardDELETE Copy to clipboard/admin/vmsguru admin Copy to clipboardPOST Copy to clipboard/admin/vmsguru/connect admin Copy to clipboardPOST Copy to clipboard/admin/vmsguru/key admin Copy to clipboardPOST Copy to clipboard/admin/vmsguru/sync admin Copy to clipboardGET Copy to clipboard/admin/vmsguru/stats admin Copy to clipboardGET Copy to clipboard/admin/vmsguru/orders/:id admin Copy to clipboardGET Copy to clipboard/vmsguru/callback state token

Security

• Copy to clipboard/vmsguru/callback sits outside Copy to clipboard/admin because it's reached by a cross-site browser redirect carrying no admin session. It's guarded by a single-use, 10-minute Copy to clipboardstate minted by the authenticated Copy to clipboardPOST /admin/vmsguru/connect 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

123
npm install
npm run dev      # medusa plugin:develop — watch + yalc push
npm run build    # medusa plugin:build

Migrations are hand-written. Copy to clipboardmedusa plugin:db:generate does not work on Windows: it globs Copy to clipboardsrc/modules/*/index.ts with a Copy to clipboardpath.joined pattern, so the pattern contains backslashes that glob treats as escapes — it matches nothing, writes no files, and still logs Copy to clipboardMigrations generated. 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 Copy to clipboardimport { Migration } from "@medusajs/framework/mikro-orm/migrations", which is not in Copy to clipboard@medusajs/framework@2.5.0's Copy to clipboardexports map and fails to resolve at both typecheck and runtime. This plugin imports from Copy to clipboard@medusajs/deps/mikro-orm/migrations instead.

Version notes

The order widget uses zone Copy to clipboardorder.details.side.after. 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.