How to Integrate Commercetools with Your Headless CMS

What is Commercetools?

Commercetools is an API-first commerce platform for building custom storefronts, marketplaces, B2B portals, and omnichannel commerce systems. Its main capabilities include product catalogs, carts, orders, pricing, promotions, customer accounts, and checkout flows. It’s widely used by enterprise retail, manufacturing, and B2B teams that need composable commerce instead of a fixed storefront stack.

Why integrate Commercetools with a headless CMS?

Commercetools is strong at commerce logic: SKUs, variants, prices, carts, inventory, promotions, and orders. But a product detail page usually needs more than commerce data. You also need buying guides, localized product stories, SEO fields, campaign badges, comparison tables, sustainability claims, and launch content that changes faster than your catalog model should.

Architecture overview

A typical Sanity and Commercetools integration starts when an editor publishes product content in Sanity Studio. A Sanity webhook, filtered with GROQ, listens for documents like _type == 'productPage' and defined(commercetoolsKey). The webhook can call a Sanity Function, or your own small API route, with the changed document ID. That handler fetches the exact fields Commercetools needs from the Content Lake using GROQ, such as the Commercetools product key, localized name, slug, description, SEO title, badges, and linked campaign references. The handler then authenticates to Commercetools with the Client Credentials flow, using the project key, client ID, client secret, auth host, and API host from your Commercetools project settings. It calls the Commercetools Product API, commonly products/key={key}, reads the current version, and sends update actions such as changeName, setDescription, changeSlug, or custom field updates. From there, the storefront can render price, availability, cart, and promotions from Commercetools, while using Sanity for editorial content, or it can use synced fields inside Commercetools where your commerce workflow requires them. The end user sees one product experience, even though the content and commerce systems stay cleanly separated.

Common use cases

Step-by-step integration

1. 1

   Create a Commercetools project and API client

   In Commercetools Merchant Center, create or select a project, note the project key, region, auth URL, and API URL, then create an API client under Developer settings. For product updates, grant scopes such as manage_products:{projectKey}. Use narrower scopes in production when possible.

2. 2

   Install the Commercetools and Sanity packages

   In your sync service, Sanity Function, or framework API route, install @commercetools/sdk-client-v2, @commercetools/platform-sdk, @sanity/client, and node-fetch if your runtime needs it.

3. 3

   Model product content in Sanity Studio

   Create a productPage schema with fields like commercetoolsKey, title, slug, shortDescription, seoTitle, locale, badges, campaign references, and feature modules. Keep prices, inventory, carts, and orders in Commercetools.

4. 4

   Create a publish trigger

   Add a Sanity webhook with a GROQ filter such as _type == 'productPage' && defined(commercetoolsKey). Send the document ID to a Sanity Function or webhook handler whenever product content is published or updated.

5. 5

   Fetch Sanity content and call the Commercetools API

   Use GROQ to fetch only the fields needed for the Commercetools update. Authenticate to Commercetools with the Client Credentials flow, fetch the product by key, include its current version, and send Product update actions.

6. 6

   Test the storefront path

   Publish a test product in Sanity, verify the Commercetools product version changes, confirm localized fields are correct, and render a page that combines Commercetools price and availability with Sanity product content.

How Sanity + Commercetools works

CMS approaches to Commercetools

Keep building

Explore related integrations to complete your content stack.