Foundry IMS

medusa-plugin-foundry-ims

Real-time integration between Medusa and Foundry IMS. Pushes order, inventory, and fulfillment events from your Medusa store to Foundry the moment they happen — replaces polling with native Medusa event subscribers.

What this plugin does

Subscribes to Medusa events and forwards them to your Foundry workspace:

Medusa event What Foundry does Copy to clipboardorder.placed Imports the order, creates inventory reservations Copy to clipboardorder.updated Updates order status, transitions reservations on shipment/refund Copy to clipboardorder.canceled Releases all active reservations Copy to clipboardfulfillment.shipment_created Records the tracking number against the order

The plugin sends a thin event envelope (Copy to clipboard{ topic, payload: { orderId } }); Foundry refetches the full order from your Medusa admin API for the rest. Your Foundry API key is the auth — no separate webhook secret to manage.

Requirements

• Medusa v2.3.0+ (plugin support landed in 2.3.0)
• Node 20+
• A Foundry IMS account at foundryims.com with:
  • A Copy to clipboardMEDUSA channel created (Sales Channels → Add Channel → Medusa)
  • An API key (Settings → API Keys → Create)

Install

123
npm install medusa-plugin-foundry-ims
# or
yarn add medusa-plugin-foundry-ims

In your Copy to clipboardmedusa-config.ts:

1234567891011
import { defineConfig } from "@medusajs/framework/utils"

module.exports = defineConfig({
  // ...your existing config...
  plugins: [
    {
      resolve: "medusa-plugin-foundry-ims",
      options: {},
    },
  ],
})

Configure

The plugin reads three environment variables:

Var Required Default Where to get it Copy to clipboardFOUNDRY_API_KEY yes — Foundry → Settings → API Keys → Create. Starts with Copy to clipboardfims_. Copy to clipboardFOUNDRY_CHANNEL_ID yes — Foundry → Sales Channels → Medusa → URL contains the channel UUID. Copy to clipboardFOUNDRY_API_URL no Copy to clipboardhttps://api.foundryims.com Override only for self-hosted or staging Foundry instances.

Add to your Medusa server's Copy to clipboard.env:

12
FOUNDRY_API_KEY=fims_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FOUNDRY_CHANNEL_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Restart your Medusa server. Place a test order — Foundry should receive it within ~1 second.

Verifying the connection

After a test order:

12
curl -H "Authorization: Bearer $FOUNDRY_API_KEY" \
  "$FOUNDRY_API_URL/api/v1/orders?limit=5"

You should see your order in the response. If not, check your Medusa logs for Copy to clipboard[medusa-plugin-foundry-ims] warnings — usually a missing env var.

Troubleshooting

Plugin warns "FOUNDRY_API_KEY and FOUNDRY_CHANNEL_ID must be set..." on startup. The plugin couldn't find one or both required env vars. Double-check your Copy to clipboard.env and that you've restarted Medusa.

Orders aren't appearing in Foundry.

1. Confirm the API key is valid (curl test above).
2. Confirm the channel ID matches the one shown in Foundry's URL.
3. Check Medusa server logs for Copy to clipboard[medusa-plugin-foundry-ims] post failed: ....
4. Confirm Copy to clipboardorderSyncEnabled is on for the Foundry channel (Foundry → Sales Channels → Medusa → Settings).

The plugin works but Foundry shows the wrong status / out-of-date inventory. Foundry refetches via the Medusa admin API on every event. Make sure the Copy to clipboardadminApiToken configured on the Foundry channel is still valid (Settings → Foundry → Sales Channels → Medusa → Edit credentials).

What this plugin does NOT do

• It does not push outbound changes (Foundry → Medusa). That direction is handled by Foundry's existing Medusa adapter.
• It does not provide an admin UI inside Medusa (yet — coming in v0.2.0).
• It does not have built-in retry logic for failed posts (yet — coming in v0.3.0). For now, Foundry's 5-minute order-sync cron is the safety net.

Roadmap

• v0.2.0 — Admin widget inside Medusa Settings: configure API key + channel ID without env vars.
• v0.3.0 — Retry queue for failed event posts. Health-check endpoint. Inventory + product subscribers.

Support

• Foundry docs
• GitHub issues
• Foundry support email

License

MIT