Headless Shopify with Next.js and the Storefront API

Shopify is the world's best commerce backend — battle-tested inventory, reliable checkout, and a mature ecosystem of apps. But default storefront themes are a constraint. Headless Shopify lets you keep the backend you trust while building any frontend experience you want in React and Next.js.

The Shopify Storefront API

The Storefront API is a public GraphQL API that exposes everything a storefront needs: products, collections, customers, carts, and checkout. You query it from your Next.js app — in Server Components for static content like product pages, or in client-side hooks for interactive operations like cart management. All you need is a Storefront API access token, available free from the Shopify admin.

Setting Up the GraphQL Client

A lightweight fetch-based GraphQL client works well for most headless Shopify setups. It keeps your bundle lean and gives you full control over caching behaviour — including Next.js's native fetch caching and revalidation.

// lib/shopify.js
const endpoint = `https://${process.env.SHOPIFY_STORE_DOMAIN}/api/2025-01/graphql.json`;

export async function shopifyFetch(query, variables = {}, options = {}) {
  const res = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Storefront-Access-Token': process.env.SHOPIFY_STOREFRONT_TOKEN,
    },
    body: JSON.stringify({ query, variables }),
    next: { revalidate: options.revalidate ?? 60 },
  });
  if (!res.ok) throw new Error(`Shopify fetch failed: ${res.status}`);
  return res.json();
}

Product Pages with Incremental Static Regeneration

Product pages are the perfect ISR use case. At build time, generate the top-selling products statically. For new products, generate on first request and cache with a 60-second revalidation so price and inventory stay current. The result is pre-rendered HTML served from Vercel's CDN edge — no server processing, no JavaScript execution needed to see the product — Lighthouse scores consistently above 95.

// app/products/[handle]/page.js
export async function generateStaticParams() {
  const { data } = await shopifyFetch(
    `query { products(first: 250) { nodes { handle } } }`
  );
  return data.products.nodes.map((p) => ({ handle: p.handle }));
}

export const revalidate = 60;

export default async function ProductPage({ params }) {
  const { data } = await shopifyFetch(PRODUCT_QUERY, { handle: params.handle });
  if (!data.product) notFound();
  return <ProductDetail product={data.product} />;
}

Cart Management with the Cart API

Shopify's Cart API is the right choice for modern headless stores. Create a cart on first add-to-cart, persist the cart ID in a cookie, and all subsequent add/remove/update operations are mutations against that cart ID. The cart state lives in Shopify — you never need to sync it to your own database.

const CREATE_CART = `
  mutation cartCreate($input: CartInput!) {
    cartCreate(input: $input) {
      cart {
        id
        checkoutUrl
        lines(first: 20) {
          nodes {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                title
                price { amount currencyCode }
                product { title featuredImage { url } }
              }
            }
          }
        }
        cost { totalAmount { amount currencyCode } }
      }
    }
  }
`;

Checkout Redirect

When the customer is ready to purchase, redirect to cart.checkoutUrl — a Shopify-hosted checkout page. You never handle payment details, and you get Shopify's battle-tested checkout with all payment methods, shipping calculations, and discount codes built in. After purchase, Shopify redirects back to your thank-you page URL.

Collection Pages and Filtering

The Storefront API supports filtering via product metafields, variant options, price ranges, and availability. Build collection pages with server-side filtering by passing filter params to the products query. For real-time count updates as users select filters, fetch filtered results client-side with a debounced query. For catalogues above 10,000 SKUs, Algolia or Shopify Search & Discovery provides faster relevance and typo tolerance.

Customer Accounts

For customer accounts in a headless store, use Shopify's hosted Customer Account API. Your store redirects to Shopify's OAuth login page, the customer authenticates, and Shopify redirects back with an access token. This keeps you out of the business of handling passwords and session management directly — the safest approach for any production store.

SEO with Product Schema

Headless Next.js gives you full control over SEO. Generate metadata dynamically from product data using Next.js generateMetadata. Add JSON-LD Product schema to every product page — this enables rich results in Google search showing price, availability, and reviews directly in the SERP. Use next/image for all product images: automatic WebP conversion, correct sizing, and lazy loading eliminates the largest image performance bottleneck in most storefronts.

International Markets

Shopify Markets lets you serve different prices and currencies per country. In a headless setup, pass the buyer's country in the @inContext directive on Storefront API queries — prices, availability, and the checkout flow localise automatically. Detect country from Vercel's geo headers or let the customer choose. Store the market context in a cookie and apply it to all queries for the session.

Real-World Performance Results

In a recent project, migrating from a Shopify Dawn theme to a custom Next.js headless frontend improved Lighthouse performance from 48 to 96. Mobile page load dropped from 4.2s to 1.1s. Mobile conversion rate increased 34% in the first quarter post-launch. The gains come from eliminating theme JavaScript overhead, serving pre-rendered HTML with ISR, and leveraging Vercel's CDN edge cache.