Connect Medusa to Foundry

A Medusa instance running 2.3.0 or later

Medusa's plugin system was introduced in 2.3.0. Older instances will need to upgrade first. Check your version with yarn medusa --version in your Medusa repo.

Your Medusa server reachable over the public internet

Foundry's prod backend pushes catalog and inventory updates to your Medusa server, so it needs to be reachable from outside your network. If your Medusa is on localhost, use a tunnel like ngrok or cloudflared during testing, or deploy it somewhere public (Render, Railway, fly.io, your own server). Your Medusa Admin URL goes in the Foundry channel settings later.

A Foundry account at app.foundryims.com

If you don't have one yet, sign up free. You'll need OWNER or ADMIN role to create channels and API keys.

Create a Medusa channel

In Foundry admin, go to Sales Channels → Add Channel. Give it a name (e.g., "My Medusa Store"), pick Medusa (self-hosted) as the platform, and click Create. You'll land on the channel detail page — note the channel ID in the URL (the UUID after /sales-channels/). You'll need it in step 3.

Add credentials so Foundry can write to Medusa

Click Settings on the channel and fill three fields:

• Medusa URL — the public URL of your Medusa server (no trailing slash, no /admin). For example https://my-medusa.com.
• Admin API Token — from Medusa admin: Settings → API Key Management → Create Secret Key with admin scope. Copy the value once and paste it here.
• Default Stock Location ID — optional. Leave blank to auto-pick your first active location.

Generate a Foundry API key

Go to Settings → API Keys → Create. Name it something recognizable (e.g., "Medusa Plugin"), copy the fims_… token. You'll only see the full value once — paste it somewhere safe for step 3.

Install

yarn add medusa-plugin-foundry-ims

Or with npm: npm install medusa-plugin-foundry-ims.

Register the plugin in medusa-config.ts

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

Add three environment variables

Append to your Medusa server's .env:

FOUNDRY_API_KEY=fims_xxxxxxxxxxxxxxxxxxxxxxxx
FOUNDRY_CHANNEL_ID=<the channel UUID from step 2>
# FOUNDRY_API_URL=https://api.foundryims.com   # optional, this is the default

Restart your Medusa server. On startup the plugin logs [medusa-plugin-foundry-ims] if config is missing — clean startup means it's wired up.

Place a test order in Medusa

Use Medusa's storefront or the test-order helper in admin to place an order. Within ~1 second it should show up in Foundry's Orders page tagged with the Medusa channel.

List a Foundry product to Medusa

Open any product in Foundry's catalog and click List. Pick your Medusa channel from the list, confirm the publish dialog, and within a few seconds the product appears in your Medusa admin under Products. Subsequent inventory or price changes in Foundry sync automatically.

Plugin warns "FOUNDRY_API_KEY and FOUNDRY_CHANNEL_ID must be set..."

One or both env vars aren't reaching the plugin. Confirm they're in .env (not just shell-exported) and restart Medusa. Some hosting providers require explicit env-var configuration rather than reading from .env — check your provider's docs.

Orders aren't appearing in Foundry

Check your Medusa server logs for [medusa-plugin-foundry-ims] post failed entries. Most common cause: the API key is invalid or doesn't have access to the channel's org. Generate a fresh key in Foundry, update the env var, restart Medusa.

Listings fail to push from Foundry to Medusa

Foundry's prod backend has to be able to reach your Medusa URL. Errors usually surface as 502/timeout in the listing dialog. If you're testing with localhost-only Medusa, use a tunnel (ngrok, cloudflared) and paste that public URL into the Foundry channel settings instead.

Status updates lag

Even without the plugin, Foundry runs a 5-minute order-sync cron against your Medusa server as a safety net. With the plugin installed, that cron is the fallback rather than the primary path — events arrive via push within a second. If you see consistent multi-minute delays, double-check the plugin is registered in your medusa-config.ts and the Medusa server has been restarted since install.