Medusa - Integration Instructions

​

Follow this integration guide to connect your Medusa data to SourceMedium.

​

How it works

​

What data SourceMedium reads

• 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)

​

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

• 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)

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

​

4. Order payload

​

5. Subscriptions (only for stores with subscriptions)

• /reporting/subscriptions returns all subscription records with created_at and updated_at.
• 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

# 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"

• 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 publishable key in your Medusa Admin (Settings → Publishable API Keys) and share it with your SourceMedium team; we update the stored credential in our connection manager with no data loss.