Medusa - Integration Instructions

Medusa is an open-source, self-hosted commerce platform. SourceMedium connects to your Medusa store with a secret API key and your backend base URL.

You connect data sources yourself in SourceMedium. Sign in to your SourceMedium account, open your store, then in the Data sources section click Connect data source and choose the platform. You need an Editor or Admin role on the store. If you have view-only access, ask an admin or editor on your team to connect it.Once it is connected, what happens next covers first-sync timing and what each connection status means.

How to connect

Paste your Medusa API key and backend base URL in SourceMedium. Do not email those values.

Create a secret API key in Medusa

In Medusa admin, go to Settings → Secret API Keys and click Create. Copy the key from the pop-up; you will not see it again. Medusa’s own guide: Manage Secret API Keys. If you use a read-only reporting projection instead, use that projection’s publishable key and confirm the /reporting routes with the checklist below.

Find your backend base URL

This is the root of your Medusa server, for example https://store.yourdomain.com. If you only know the admin dashboard URL, drop a trailing /app.

Add both values in SourceMedium

Find Medusa in the connector picker and click Connect. Enter:

API key: the secret or publishable key from the previous step
Base URL: https://store.yourdomain.com

Click Connect. SourceMedium checks the credentials before saving them.

Confirm it is connected

The connection reads Awaiting first data until the first sync lands, then Connected.

SourceMedium only ever reads from your connected platforms. It does not create, change, or delete anything, so create the key with read-only access wherever the platform offers it. Treat it like a password: keep it confidential and avoid sharing it over email or in spreadsheets. If the credential is rotated or revoked, follow this guide’s connection method to update SourceMedium.

What data syncs

Orders, including line items, shipping lines, fulfillments, and refunds
Customers
Products and variants
Inventory items and levels
Subscriptions, when your store runs a subscription module that exposes them

Projection requirements (for your developer)

Expose a /reporting API on the store’s Medusa backend meeting this exact contract. Every requirement below comes from a production-validated integration. Meeting them up front means validation passes on the first try.

1. Authentication

Requests carry the store’s publishable API key in the x-publishable-api-key header.
The projection must reject requests without a valid key.

2. Routes and response envelope

Expose these five GET routes:

Route	Returns
`/reporting/orders`	Orders with inline children (see below)
`/reporting/customers`	Customer records
`/reporting/products`	Products with nested `variants[]` (including `prices[]`)
`/reporting/inventory`	Inventory items with nested `location_levels[]`. Envelope key is `inventory_items` (not `inventory`)
`/reporting/subscriptions`	Subscription records (only if the store has subscriptions)

Every route must:

Support offset/limit pagination: ?limit=200&offset=0 (limit up to 200).
Respond with the envelope { "<resource>": [...], "count": N, "offset": n, "limit": l }, where count is the total number of records. The <resource> key matches the route name for every route except /reporting/inventory, whose key is inventory_items.
Return records in a stable sort order (for example, created_at descending) so paginated reads are consistent.

3. Order filtering (required for backfill)

/reporting/orders must accept created_from and created_to ISO-8601 query params and filter server-side, both bounds inclusive:

GET /reporting/orders?created_from=2025-03-01T00:00:00.000Z&created_to=2025-04-01T00:00:00.000Z&limit=200

SourceMedium uses these to backfill history in 30-day windows. Without them, historical backfill is not possible.

4. Order payload

Each order must include all of the following. Fields marked Commonly missed are the ones that most often fail validation. Each was a real issue that blocked or delayed a past onboarding.

Field	Requirement
`id`, `status`, `created_at`, `updated_at`	Always populated. `status` = pending / completed / canceled.
`payment_status`, `fulfillment_status`	Commonly missed. Populated on every order that has them.
`canceled_at`	Populated on canceled orders.
`currency_code`	ISO currency code for the order’s native currency. Send the source value; do not convert it before delivery.
Money totals: `total`, `subtotal`, `tax_total`, `discount_total`, `shipping_total`, `item_total`, `paid_total`, `refunded_total`	Commonly missed. Computed real values on every order, including historical ones, not `0` and not `null`. Major currency units (`6990` = ₱6,990.00 or $6,990.00).
Capture details: `paid_total`, `net_captured`, `over_captured`, `captures[]`	Commonly missed. `captures[]` is the payment capture ledger (empty array `[]` when nothing is captured, not missing).
`items[]`	Commonly missed. Line items inline on every order, including the oldest historical orders. Each item: `id`, `quantity` (ordered, non-null), `unit_price` (pre-discount), `subtotal` (pre-discount), `total` (post-discount), `tax_total`, `discount_total`.
`shipping_methods[]`	Shipping lines inline, each with its `amount`.
`fulfillments[]`	Fulfillments inline, including tracking details and which line items were fulfilled.
`refunds[]`	Commonly missed. Refunds as a top-level array on the order (not nested inside payments), each with `id`, `amount`, `currency_code`, `created_at`.
`metadata`	Included as-is. If recurring orders link to subscriptions through metadata keys, preserve those keys.

5. Subscriptions (only for stores with subscriptions)

/reporting/subscriptions returns all subscription records with created_at and updated_at.
Subscription currency and money fields must use their native source values. SourceMedium applies reporting-currency conversion downstream when it is enabled for the workspace.
There must be a way to link a recurring order to its subscription, typically a subscription ID in the order’s metadata. The exact metadata keys are merchant-specific; SourceMedium reviews them during onboarding.
Note: subscription history only covers what your subscription module has synced into Medusa. If your provider started syncing recently, SourceMedium reports from that point forward.

6. Self-test checklist

Before handing off to SourceMedium, verify all of the following with curl:

# 1. Auth works
curl -H "x-publishable-api-key: pk_YOUR_KEY" https://YOUR_BASE_URL/reporting/orders?limit=1

# 2. Pagination envelope is present (count/offset/limit)
# 3. Date filter works: a narrow window returns fewer orders:
curl -H "x-publishable-api-key: pk_YOUR_KEY" \
  "https://YOUR_BASE_URL/reporting/orders?created_from=2025-03-01T00:00:00.000Z&created_to=2025-03-07T00:00:00.000Z&limit=200"

Then confirm, by inspecting real responses:

A recent completed order has non-zero total, subtotal, item_total, and non-empty items[] with non-null quantity.
An order from your oldest month of business also has computed money totals and non-empty items[] (not header-only).
A refunded order has a top-level refunds[] array with the refund amount.
A canceled order has canceled_at populated.
An order with a partial capture has captures[] entries and net_captured set.
/reporting/products includes variants[] with prices[].
/reporting/inventory includes location_levels[].
All five routes reject a request with a missing or invalid key.

Data coverage notes

Returns and exchanges are not currently collected for Medusa stores.
Marketing attribution: Medusa has no built-in customer-journey source, so attribution models receive no Medusa-native input.
After the initial backfill, SourceMedium syncs your Medusa data automatically every 6 hours.

Troubleshooting

Validation failed on money fields? The projection is returning 0 or null instead of computed totals. This is the most common issue. Your developer must compute totals on the backend, including for historical orders.
Revenue looks off by 100x? Currency units were not confirmed. Contact your account manager to re-verify whether your projection emits major or minor units.
Old orders have no line items? The projection is only hydrating items[] for recent orders. It must hydrate them for all history.
Need to rotate a key? Create a new key in your Medusa Admin (Settings → Secret API Keys, or Publishable API Keys for a reporting projection) then paste it in SourceMedium on the Medusa connection (Reconnect). The new key replaces the stored credential with no data loss.

Integrations

Ecommerce & Subscription

Marketing & Advertising

Email & SMS

Customer Success & Operations

Analytics & Measurement

Finance

Data Infrastructure

Configuration Sheet

Tracking setup

Health checks

Medusa - Integration Instructions

How to connect

What data syncs

Projection requirements (for your developer)

1. Authentication

2. Routes and response envelope

3. Order filtering (required for backfill)

4. Order payload

5. Subscriptions (only for stores with subscriptions)

6. Self-test checklist

Data coverage notes

Troubleshooting

​How to connect

​What data syncs

​Projection requirements (for your developer)

​1. Authentication

​2. Routes and response envelope

​3. Order filtering (required for backfill)

​4. Order payload

​5. Subscriptions (only for stores with subscriptions)

​6. Self-test checklist

​Data coverage notes

​Troubleshooting

How to connect

What data syncs

Projection requirements (for your developer)

1. Authentication

2. Routes and response envelope

3. Order filtering (required for backfill)

4. Order payload

5. Subscriptions (only for stores with subscriptions)

6. Self-test checklist

Data coverage notes

Troubleshooting