channels/medusa

MedusaJS & Open-Source Stores

Bearer tokens, Base API URL, health checks, and Admin product mapping for Medusa-compatible stores.

Who this is for

Use this destination when the store is **yours**: MedusaJS, or a custom Admin API that accepts the same POST /admin/products shape. This is how eListSync talks to open-source storefronts without pretending they are Shopify.

Lab bridge (port 9000)

The repo can clone medusajs/medusa-starter-default into tests/external-storefront and run a Medusa-compatible admin bridge on **port 9000**.

bash

npm run storefront:github
curl http://127.0.0.1:9000/health

Set TOKSYNC_ALLOW_LOCAL_INGEST=1 if you will scrape a local storefront URL. Do not enable that flag on a public deployment.

Connect in Destinations

Destinations → Custom Open-Source Webstore / Medusa:

Base API URL: http://localhost:9000 (lab) or https://admin.yourstore.com
API Key: Bearer token (toksync_medusa_admin_dev_key in the lab)

eListSync verifies GET /health and GET /admin/store **before** saving. A 404 on health means the destination is not saved. That is the correct failure.

Schema mapping

Canonical variants map to Medusa Admin POST /admin/products:

Options such as Color and Size
Prices in **minor units** (7999 = 79.99 USD)
inventory_quantity per variant
Image URLs

Handle collisions: if the handle already exists on the Medusa store, the API error is logged. Change the canonical handle or update the existing Medusa product through your usual ops process.

Production Medusa

Use HTTPS, a real admin user token, and network rules that allow the eListSync workers to reach the Admin API. Rotate tokens. Do not use the lab key outside local development.

Common errors

Health check failed — wrong port, Medusa not running, or path prefix
401 Bearer — token expired or not an admin
Price 0 — canonical price missing; ingest did not parse currency
Options empty — variants had no Size/Color; Medusa still needs at least a default variant