How to Integrate Shopify with Your Headless CMS

What is Shopify?

Shopify is a commerce platform for selling products online, in person, and across marketplaces. It handles product catalogs, variants, inventory, checkout, payments, orders, discounts, and fulfillment workflows. Millions of merchants use Shopify, from small direct-to-consumer brands to public companies running multi-region stores.

Why integrate Shopify with a headless CMS?

Shopify is great at commerce logic: SKUs, inventory, pricing, checkout, taxes, and orders. The problem starts when the content around the product gets bigger than a title, a description, and a few images. A winter jacket product page might need fit guidance, material care, sustainability claims, athlete quotes, localized sizing notes, campaign modules, and comparison content. Keeping that content only inside Shopify fields can get cramped fast.

Architecture overview

A typical Shopify and Sanity integration starts with structured product content in the Content Lake. Editors update a product story, buying guide, collection intro, or localized SEO field in Sanity Studio. On publish, a Sanity webhook fires with the document ID, or a Sanity Function runs directly from the content mutation. The handler uses GROQ to fetch only the fields Shopify needs, including referenced content such as collection copy, brand details, and care instructions. It then calls Shopify's Admin GraphQL API, usually productUpdate, metafieldsSet, metaobjectUpsert, or collectionUpdate, to write those values into Shopify product metafields, collection metafields, or metaobjects. From there, the storefront can read commerce data through Shopify's Storefront API, read content directly from Sanity, or use the Shopify metafields that were synced. The end user sees a product page with accurate pricing and availability from Shopify, plus structured content that was reviewed and published in Sanity.

Common use cases

Step-by-step integration

1. 1

   Set up Shopify API access

   Create or choose a Shopify store, then create a custom app in the Shopify admin. Add Admin API scopes such as write_products, read_products, write_metaobjects, and write_metaobjects if you're syncing product metafields or metaobjects. Install the app and copy the Admin API access token.

2. 2

   Install the SDKs

   In your sync project, install @shopify/shopify-api and @sanity/client. If you're using Next.js, add a route handler. If you want the sync to run inside Sanity's event system, use a Sanity Function and keep the same Shopify Admin GraphQL call.

3. 3

   Model commerce content in Sanity Studio

   Create schemas for product marketing content, collection content, buying guides, or brand details. Include the Shopify product GID, such as gid://shopify/Product/1234567890, so each Sanity document maps to the correct Shopify product.

4. 4

   Create the publish trigger

   Create a Sanity webhook that fires when a product marketing document is published, updated, or deleted. Use a projection that includes _id and _type. For higher trust, verify the Sanity webhook signature before making the Shopify API request.

5. 5

   Call Shopify's Admin GraphQL API

   Use GROQ to fetch exactly the content fields Shopify needs, then call metafieldsSet, productUpdate, collectionUpdate, or a metaobject mutation. Keep Shopify as the source for inventory, price, variants, and checkout.

6. 6

   Test the storefront experience

   Preview a Sanity change, publish it, confirm that the Shopify metafield or metaobject updates, then render it in your storefront. For Hydrogen, Next.js, or another frontend, test both data paths: Shopify Storefront API for commerce data, and Sanity for rich editorial content.

Code example

import "@shopify/shopify-api/adapters/node";
import {shopifyApi, ApiVersion} from "@shopify/shopify-api";
import {createClient} from "@sanity/client";
import {NextRequest, NextResponse} from "next/server";

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: "production",
  apiVersion: "2025-01-01",
  token: process.env.SANITY_READ_TOKEN!,
  useCdn: false
});

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  scopes: ["write_products"],
  hostName: process.env.APP_HOST!,
  apiVersion: ApiVersion.January25,
  isEmbeddedApp: false
});

export async function POST(req: NextRequest) {
  const {_id} = await req.json();

  const product = await sanity.fetch(`
    *[_type == "productMarketing" && _id == $id][0]{
      shopifyProductGid,
      seoTitle,
      teaser,
      careInstructions
    }
  `, {id: _id});

  if (!product?.shopifyProductGid) {
    return NextResponse.json({skipped: true});
  }

  const session = shopify.session.customAppSession(process.env.SHOPIFY_SHOP!);
  session.accessToken = process.env.SHOPIFY_ADMIN_ACCESS_TOKEN!;

  const graphql = new shopify.clients.Graphql({session});

  await graphql.request(`
    mutation SetProductContent($metafields: [MetafieldsSetInput!]!) {
      metafieldsSet(metafields: $metafields) {
        metafields { id key }
        userErrors { field message }
      }
    }
  `, {
    variables: {
      metafields: [
        {
          ownerId: product.shopifyProductGid,
          namespace: "sanity",
          key: "teaser",
          type: "single_line_text_field",
          value: product.teaser || ""
        },
        {
          ownerId: product.shopifyProductGid,
          namespace: "sanity",
          key: "care_instructions",
          type: "multi_line_text_field",
          value: product.careInstructions || ""
        }
      ]
    }
  });

  return NextResponse.json({ok: true});
}

How Sanity + Shopify works

CMS approaches to Shopify

Keep building

Explore related integrations to complete your content stack.