How to Integrate Medusa with Your Headless CMS

What is Medusa?

Medusa is an open-source commerce platform built with Node.js and TypeScript. It gives developers APIs and modules for products, carts, orders, customers, pricing, promotions, fulfillment, and payments. Teams use it when they want custom commerce flows without being locked into a hosted storefront or a fixed admin experience.

Why integrate Medusa with a headless CMS?

Medusa is great at commerce logic: variants, regions, prices, carts, orders, payments, and fulfillment. But most product experiences need more than SKU data. A product detail page might need ingredient claims, editorial copy, comparison charts, campaign badges, localized buying guides, and launch content that changes on a schedule. Keeping that material inside Medusa can make your commerce data model carry content work it wasn't built for.

Connecting Medusa to a headless CMS category tool lets each system do the right job. Medusa owns transactional data, while structured content in Sanity's Content Lake owns product storytelling, landing pages, campaign modules, SEO fields, and channel-specific copy. With GROQ, you can query exactly the fields Medusa needs, like title, slug, merchandising tags, hero image, and linked collection IDs. With webhooks or Functions, a publish event can call Medusa's Admin API within seconds instead of waiting for a nightly sync.

The disconnected version is usually spreadsheet-driven. Someone copies launch copy into Medusa, another person updates a storefront JSON file, and a third person checks whether the mobile app has the same promo text. That works for 20 SKUs. It gets messy at 2,000 SKUs, 6 regions, and 3 sales channels. The trade-off is that you do need to design ownership clearly. Medusa should remain the source for prices, inventory, and orders. Sanity should own the structured content that surrounds those commerce objects.

Architecture overview

A typical Sanity and Medusa integration starts with structured product and merchandising content in the Content Lake. Editors work in Sanity Studio, where a product document might include a Medusa product ID, slug, SEO title, description, badges, rich product details, market-specific content, and references to collections or campaigns. When an editor publishes a product document, a Sanity webhook fires. The webhook can send the changed document ID to a route in your app, or a Sanity Function can run the sync logic directly on the content mutation without separate infrastructure. The handler uses GROQ to fetch only the fields Medusa needs, including joined data from referenced campaign, collection, or asset documents. From there, the handler calls Medusa's Admin API. For example, it can POST to /admin/products to create a product shell, POST to /admin/products/{id} to update title, handle, description, thumbnail, metadata, or external_id, and keep pricing, variants, inventory, and fulfillment data inside Medusa. Your storefront then reads commerce data from Medusa's Store API and content data from Sanity, either at request time, build time, or through live subscriptions for preview experiences.

Common use cases

Step-by-step integration

1. 1

   Set up Medusa

   Create a Medusa project with the Medusa CLI or start from Medusa Cloud. Configure Postgres, run migrations, create an admin user, and generate the Admin API token or auth flow your sync service will use. Install the SDK with npm install @medusajs/js-sdk.

2. 2

   Model commerce content in Sanity Studio

   Create schemas for product content, campaigns, buying guides, and collections. Include fields like title, slug, shortDescription, mainImage, seoTitle, seoDescription, merchandisingBadges, and medusa.productId. Keep price, inventory, fulfillment, and order fields in Medusa.

3. 3

   Create the publish trigger

   Add a Sanity webhook that fires on product publish, or use a Sanity Function if you want the sync code to run on Sanity content events. Filter the trigger with GROQ so it only runs for documents where _type == 'product'.

4. 4

   Fetch the exact Sanity fields with GROQ

   In your handler, use @sanity/client to fetch the published document and join asset URLs, campaign references, collection handles, and localized fields. Don't send the whole document to Medusa if Medusa only needs six fields.

5. 5

   Call Medusa's Admin API

   Use the Medusa JS SDK or Admin REST API to create or update the product. Map Sanity fields to Medusa fields such as title, handle, description, thumbnail, external_id, and metadata. Store the Medusa product ID back on the Sanity document after the first create.

6. 6

   Test the storefront flow

   Publish a draft product in Sanity, confirm the webhook runs, inspect the product in Medusa Admin, and load the storefront. Test updates, deletes, localization, image changes, and rollback behavior before giving editors access.

How Sanity + Medusa works

CMS approaches to Medusa

Keep building

Explore related integrations to complete your content stack.