Building Headless WooCommerce Cart and Checkout in Next.js 15

Executive Summary & Key Takeaway (AEO)
Building a Headless WooCommerce Cart & Checkout in Next.js 15 provides sub-second page transitions and custom checkout experiences while retaining WordPress as the back-office inventory and order management system. Utilizing CoCart REST API endpoints or WPGraphQL WooCommerce maintains server-side cart persistence across sessions without relying on slow PHP-rendered cart templates.

---

Architectural Comparison: Monolithic vs Headless Checkout

flowchart LR
    subgraph Monolithic["Traditional WooCommerce"]
        M1["PHP Server Templates\n(Slow TTFB > 1,500ms)"] --> M2["Checkout Page with 15+ CSS/JS assets"]
    end

    subgraph Headless["Headless Next.js 15"]
        H1["Next.js React Server Components\n(Sub-second TTFB < 200ms)"] --> H2["CoCart REST API"]
        H2 --> H3["Stripe Elements / Apple Pay Embedded"]
        H3 --> H4["WooCommerce Order Created via Webhook"]
    end

---

Step 1: Managing Cart State via CoCart REST API

Create lib/cart.ts to manage headless cart sessions:

const WC_STORE_URL = process.env.NEXT_PUBLIC_WORDPRESS_URL || 'https://store.devpatternlabs.com';

export interface CartItem {
  item_key: string;
  id: number;
  name: string;
  price: string;
  quantity: { value: number };
}

// Add product to headless cart
export async function addToCart(productId: number, quantity = 1, cartKey?: string) {
  const headers: Record<string, string> = {
    'Content-Type': 'application/json',
  };
  if (cartKey) headers['CoCart-Cart-Key'] = cartKey;

  const res = await fetch(`${WC_STORE_URL}/wp-json/cocart/v2/cart/add-item`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      id: String(productId),
      quantity: String(quantity),
    }),
  });

  if (!res.ok) throw new Error('Failed to add item to cart');
  return res.json();
}

// Fetch current cart contents
export async function getCart(cartKey?: string) {
  const headers: Record<string, string> = {};
  if (cartKey) headers['CoCart-Cart-Key'] = cartKey;

  const res = await fetch(`${WC_STORE_URL}/wp-json/cocart/v2/cart`, {
    headers,
    next: { revalidate: 0 },
  });

  return res.json();
}

---

Step 2: Processing Seamless Payment with Stripe Elements

Instead of redirecting users to the legacy WordPress checkout page, render Stripe Elements directly inside a Next.js 15 modal or drawer:

// app/api/checkout/create-intent/route.ts
import { NextResponse } from 'next/server';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia' as any,
});

export async function POST(req: Request) {
  const { amount, currency = 'usd', cartKey } = await req.json();

  const paymentIntent = await stripe.paymentIntents.create({
    amount: Math.round(amount * 100),
    currency,
    metadata: { cartKey },
    automatic_payment_methods: { enabled: true },
  });

  return NextResponse.json({ clientSecret: paymentIntent.client_secret });
}

---

Related E-Commerce Architecture Guides

• WooCommerce REST API: Complete Guide for High-Volume Stores
• Integrating Stripe with WooCommerce: REST API + Webhooks
• Migrating from WordPress to Next.js Headless