Headless eCommerce with Shopify and Next JS

By Kokil Thapa | Last reviewed: September 2026

Headless eCommerce with Shopify and Next JS decouples Shopify’s order, inventory, and payment engine from the customer-facing site. You keep Shopify Admin for products, fulfilment, and reporting. You build the storefront in Next.js for layout freedom, Core Web Vitals, and editorial content. That split suits brands outgrowing Liquid themes but not ready to leave Shopify’s checkout and ops stack. If you sell across Nepal and abroad, the pattern also helps with multi-currency storefronts without fighting theme limits. This guide walks through architecture, API wiring, checkout choices, and production gotchas from real eCommerce builds.

What is headless eCommerce with Shopify and Next JS?

Traditional Shopify stores render HTML from Liquid templates on Shopify’s servers. A headless setup moves presentation to your Next.js app on Vercel, Netlify, or your own Node host. Shopify remains the system of record for SKUs, stock, discounts, and orders.

The contract between the two layers is GraphQL. The Shopify Storefront API exposes products, collections, cart lines, and checkout URLs. Your Next app never touches the Admin API from the browser. That boundary keeps private tokens off the client.

On client projects I have shipped with Shopify APIs, the headless split pays off when marketing wants a content-heavy homepage, lookbooks, or custom product configurators. It costs more than a theme. You own frontend deploys, caching, and SEO plumbing that Liquid gives you for free.

Monolith theme vs headless split

A Liquid theme keeps routing, templates, and checkout under one domain managed in Shopify. Headless adds a second deploy surface and API versioning discipline. You gain component reuse, modern JS tooling, and edge caching. You lose the simplicity of theme editor tweaks by non-developers.

For a wider platform comparison, see the Magento vs Shopify vs WooCommerce breakdown. Headless Shopify often wins when ops already live in Shopify but the storefront must feel bespoke.

How do you connect Next JS to the Shopify Storefront API?

Start with a Custom App in Shopify Admin. Enable Storefront API access and copy the public Storefront access token plus your shop domain. Pin the API version to 2026-07 or newer so quarterly deprecations do not break queries mid-year.

Install dependencies on Node.js 26 LTS with npm 12:

npm create next-app@latest shop-headless --typescript --app --eslint
cd shop-headless
npm install @shopify/storefront-api-client graphql

Create a server-only client wrapper. Never expose the private Admin token in Next.js client bundles.

/* lib/shopify.ts */
import { createStorefrontApiClient } from '@shopify/storefront-api-client';

export const shopify = createStorefrontApiClient({
  storeDomain: process.env.SHOPIFY_STORE_DOMAIN!,
  apiVersion: '2026-07',
  publicAccessToken: process.env.SHOPIFY_STOREFRONT_TOKEN!,
});

export async function shopifyFetch<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
  const { data, errors } = await shopify.request(query, { variables });
  if (errors) throw new Error(JSON.stringify(errors));
  return data as T;
}

Add environment variables in .env.local:

SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_STOREFRONT_TOKEN=shpat_storefront_public_token_here

Fetch products with a typed GraphQL query

Use colocated GraphQL strings or codegen. Keep queries minimal to stay under cost limits.

const PRODUCT_QUERY = `
  query Product($handle: String!) {
    product(handle: $handle) {
      id
      title
      descriptionHtml
      featuredImage { url altText width height }
      variants(first: 20) {
        nodes { id title availableForSale price { amount currencyCode } }
      }
    }
  }
`;

/* app/products/[handle]/page.tsx */
export default async function ProductPage({ params }: { params: { handle: string } }) {
  const data = await shopifyFetch<{ product: Product }>(PRODUCT_QUERY, { handle: params.handle });
  if (!data.product) notFound();
  return <ProductDetail product={data.product} />;
}

Validate JSON responses during development with a JSON formatter when debugging GraphQL payloads. Small syntax errors in queries fail silently until runtime.

Caching and revalidation

Product handles rarely change. Prices and inventory do. Use Incremental Static Regeneration with a sensible revalidate window, often 60–300 seconds for mid-size catalogs. Wire Shopify webhooks to a Next.js Route Handler that calls revalidatePath or revalidateTag when products update.

Read the dedicated Storefront API guide for pagination, metafields, and rate-limit headers. Metafields power size guides, specs, and SEO blocks your theme used to hard-code.

Should you use Shopify Hydrogen or a custom Next JS storefront?

Shopify Hydrogen is Shopify’s React framework built on Remix and Oxygen hosting. It ships with cart hooks, analytics bridges, and Storefront API helpers. A custom Next.js app gives you full App Router control, Vercel ecosystem plugins, and easier mixing of marketing CMS routes.

Choose Hydrogen when your team wants Shopify’s paved path and may deploy to Oxygen. Choose Next.js when SEO-led content, internationalized routing, or an existing Next monorepo already exists. The Hydrogen vs custom React storefront article compares trade-offs in more depth.

• Hydrogen: Faster Shopify-native setup, opinionated data layer, Oxygen deploy.
• Next.js: Flexible rendering modes, broad hosting choice, rich CMS integration.
• Both: Still redirect to Shopify Checkout unless you qualify for custom checkout solutions.

I normally reach for Liquid or WooCommerce on budget-sensitive Nepal storefronts. When a brand already pays for Shopify Plus or needs editorial UX, headless Next.js is a rational step. See our international florist eCommerce work for multi-currency ops patterns that inform API design even on monolith stacks.

How do you handle cart, checkout, and payments in headless Shopify?

Modern Storefront Cart API replaces the deprecated Checkout API for buyer-facing flows. You create a cart, add line items by variant ID, attach buyer identity, then read checkoutUrl for payment.

Cart mutations from a Next.js Server Action or Route Handler

const CART_CREATE = `
  mutation CartCreate($lines: [CartLineInput!]!) {
    cartCreate(input: { lines: $lines }) {
      cart { id checkoutUrl totalQuantity }
      userErrors { field message }
    }
  }
`;

/* Called from AddToCart button via server action */
export async function addToCart(variantId: string, quantity: number) {
  const cartId = cookies().get('cartId')?.value;
  if (!cartId) {
    const created = await shopifyFetch(CART_CREATE, { lines: [{ merchandiseId: variantId, quantity }] });
    cookies().set('cartId', created.cartCreate.cart.id, { httpOnly: true, secure: true, sameSite: 'lax' });
    return created.cartCreate.cart.checkoutUrl;
  }
  /* cartLinesAdd mutation for existing cart */
}

Redirect the browser to checkoutUrl. Shopify hosts PCI-sensitive payment fields. Nepal merchants often need local payment gateway workarounds because native Shopify Payments availability differs by market. Confirm which gateways your Shopify plan exposes before promising eSewa or Khalti on checkout.

For cross-border stores, display NPR or AUD prices using Shopify Markets or manual currency formatting on the Next layer. Fulfilment logic still lives in Admin. Pair this with cross-border selling guidance for duties and shipping labels.

Webhooks and order sync

Register Admin API webhooks for orders/create, products/update, and inventory_levels/update. Point them to a secured Next.js Route Handler. Verify HMAC signatures before processing. This keeps ISR pages fresh and triggers internal alerts.

Deeper Admin automation belongs in a small API integration service if queues, retries, or ERP mapping grow beyond a single handler file. The Shopify Admin API guide covers scopes and token rotation.

How do you deploy, secure, and optimize a Next JS headless Shopify store?

Treat secrets as server-only. The Storefront public token can ship to the client for direct Storefront calls, but many teams proxy GraphQL through Route Handlers to hide query shapes and apply rate limiting. Never expose Admin API tokens in Next.js.

Production checklist

1. Pin Shopify API version 2026-07 in env and CI.
2. Enable HTTP security headers in next.config.ts.
3. Map canonical URLs and structured data on product templates.
4. Configure Shopify Markets for currency and language targets.
5. Set up webhook HMAC verification and idempotent handlers.
6. Monitor Storefront API throttle headers and backoff on 429 responses.
7. Run Lighthouse on PDP and PLP routes after each release.

SEO does not come free in headless mode. You must render meta tags, Open Graph images, and Product schema yourself. Follow Shopify SEO practices for 2026 and the product page SEO guide. Pair technical markup with technical SEO audits before launch.

Performance work belongs in both layers. Optimize Next.js images with next/image and Shopify CDN URLs. Defer client JS on listing pages. Consider Core Web Vitals tuning if LCP slips above 2.5 seconds on mobile Nepal networks.

Scalability notes

GraphQL cost limits cap burst traffic. Cache product lists at the edge. Paginate collections instead of fetching entire catalogs. For flash sales, prewarm ISR paths and shorten revalidate windows temporarily.

Read scalability patterns for Nepali eCommerce even if you host abroad. Latency to Shopify’s API regions still affects add-to-cart responsiveness.

Analytics and ops

Fire GA4 purchase events from the thank-you route or Shopify pixel where possible. Align metrics with eCommerce KPIs you should track. Ops staff keep using Shopify Admin for refunds, partial fulfils, and customer service.

If you migrate from WooCommerce, plan SKU and redirect mapping first. The Shopify migration guide reduces downtime risk. Custom Laravel carts like Quick And Easy Nepalese Grocery follow different headless patterns but share the same checkout trust requirements.

Common mistakes

• Calling Admin API from client components and leaking tokens.
• Ignoring API version sunsets — schedule quarterly review.
• Building a custom checkout without understanding PCI scope.
• Skipping redirect rules when replacing an old Liquid domain structure.
• Over-fetching GraphQL fields and hitting cost ceilings during crawls.

Official references: Next.js App Router documentation for rendering modes, and Shopify Storefront API reference for cart and product objects.

Key Takeaways

• Headless eCommerce with Shopify and Next JS separates storefront UX from Shopify’s commerce core via the Storefront API.
• Use Cart API mutations server-side, then redirect buyers to Shopify Checkout for PCI-safe payments.
• Combine ISR, webhooks, and tagged revalidation so prices and stock stay accurate without sacrificing speed.
• Choose Next.js over Hydrogen when SEO content, CMS fusion, or an existing Next stack drives the decision.
• Pin API version 2026-07+, guard tokens, and plan SEO schema manually — headless removes Liquid helpers.
• Budget for longer build time versus a theme; ops still live in Shopify Admin after launch.

People Also Ask

Is Shopify headless free?

Shopify plan fees still apply. You also pay for Next.js hosting, developer time, and any CMS. The Storefront API itself does not add a separate Shopify line item, but operational complexity rises compared with a standard theme.

Can you use Next.js with Shopify without Plus?

Yes. Standard Shopify plans expose the Storefront API and hosted checkout redirect. Shopify Plus adds higher API limits, custom checkout extensibility, and B2B features. Most mid-market headless MVPs launch on standard plans first.

Does headless Shopify hurt SEO?

Not if you implement SSR or ISR with correct metadata, canonical tags, and Product schema. Headless can improve Core Web Vitals when tuned. It hurts SEO when teams ship client-only rendering on product routes or omit redirects after replatforming.

What is the alternative to Next.js for Shopify headless?

Shopify Hydrogen, Nuxt, Astro, or mobile apps consuming the same Storefront API. Some teams pair a Laravel or WordPress marketing site with a Shopify buy button. Pick the framework your team can maintain for three years, not only at launch.

Build headless Shopify the right way

Headless eCommerce with Shopify and Next JS trades theme simplicity for frontend control. Map your catalog API, cart flow, and checkout redirect before writing UI components. Plan SEO, webhooks, and Nepal payment realities early so you do not rebuild at launch.

If you want a storefront audit, migration plan, or full build, contact us or explore eCommerce development services. For related reading, browse search UX patterns, cart abandonment fixes, and starting eCommerce in Nepal.