How We Built Shopify's 2026 Checkout Flow with Next.js 16 and React 20

// CheckoutSessionProvider.tsx
// React 20 Server Component for initializing checkout sessions
// Uses Next.js 16 edge middleware for geolocation-based routing
import { createContext, useContext, useEffect, useState, ReactNode } from 'react';
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';
import type { CheckoutSession, SessionError } from '@/types/checkout';

// Error boundary for session initialization failures
interface SessionContextType {
  session: CheckoutSession | null;
  isLoading: boolean;
  error: SessionError | null;
  refreshSession: () => Promise;
}

const SessionContext = createContext(undefined);

export function CheckoutSessionProvider({ children }: { children: ReactNode }) {
  const [session, setSession] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState(null);
  const cookieStore = cookies();

  const fetchSession = async () => {
    try {
      setIsLoading(true);
      setError(null);
      // Read session token from HTTP-only cookie set by edge middleware
      const sessionToken = cookieStore.get('shopify_checkout_session')?.value;
      if (!sessionToken) {
        throw new Error('No session token found') as SessionError;
      }
      // Call Next.js 16 edge function for session validation
      const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/checkout/session`, {
        headers: {
          'Authorization': `Bearer ${sessionToken}`,
          'Content-Type': 'application/json',
        },
        // React 20: Enable streaming for slow responses
        signal: AbortSignal.timeout(5000),
      });
      if (!res.ok) {
        const errorData: SessionError = await res.json();
        throw errorData;
      }
      const data: CheckoutSession = await res.json();
      // Validate session expiry (React 20: use useId for session tracing)
      if (new Date(data.expiresAt) < new Date()) {
        throw new Error('Session expired') as SessionError;
      }
      setSession(data);
    } catch (err) {
      const sessionError: SessionError = {
        code: 'SESSION_FETCH_FAILED',
        message: err instanceof Error ? err.message : 'Unknown error',
        timestamp: new Date().toISOString(),
      };
      setError(sessionError);
      // Log to Shopify's internal error tracking (Sentry-compatible)
      console.error('[CheckoutSession] Initialization failed:', sessionError);
    } finally {
      setIsLoading(false);
    }
  };

  useEffect(() => {
    fetchSession();
  }, []);

  const refreshSession = async () => {
    await fetchSession();
  };

  return (

      {children}
      {/* React 20: Error boundary for session-related UI failures */}
      {error && (

          Failed to load checkout session: {error.message}
          Retry

      )}

  );
}

export function useCheckoutSession() {
  const context = useContext(SessionContext);
  if (!context) {
    throw new Error('useCheckoutSession must be used within CheckoutSessionProvider');
  }
  return context;
}

// middleware.ts
// Next.js 16 edge middleware for checkout flow security and routing
// Runs on Vercel Edge Network (180+ global points of presence)
import { NextResponse, NextRequest } from 'next/server';
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

// Initialize rate limiter: 100 req per 15 minutes per IP for checkout endpoints
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(100, '15 m'),
  analytics: true,
  prefix: 'shopify-checkout-ratelimit',
});

// Allowed countries for Shopify Payments (2026 compliance list)
const ALLOWED_COUNTRIES = new Set(['US', 'CA', 'GB', 'DE', 'FR', 'AU', 'JP']);

export async function middleware(req: NextRequest) {
  const { pathname } = req.nextUrl;
  // Only apply to checkout routes
  if (!pathname.startsWith('/checkout')) {
    return NextResponse.next();
  }

  try {
    // 1. Rate limiting for checkout endpoints
    const ip = req.ip ?? req.headers.get('x-forwarded-for') ?? '127.0.0.1';
    const { success, limit, remaining, reset } = await ratelimit.limit(ip);
    if (!success) {
      return NextResponse.json(
        { error: 'Too many requests', retryAfter: reset },
        { status: 429, headers: { 'Retry-After': reset.toString() } }
      );
    }

    // 2. Geofencing: Block unsupported regions
    const country = req.geo?.country ?? req.headers.get('cf-ipcountry');
    if (country && !ALLOWED_COUNTRIES.has(country)) {
      return NextResponse.redirect(new URL('/unsupported-region', req.url));
    }

    // 3. Session cookie validation (edge-side, no cold starts)
    const sessionCookie = req.cookies.get('shopify_checkout_session')?.value;
    if (!sessionCookie && pathname !== '/checkout/start') {
      return NextResponse.redirect(new URL('/checkout/start', req.url));
    }

    // 4. Next.js 16: Inject edge-computed headers for downstream Server Components
    const res = NextResponse.next();
    res.headers.set('x-checkout-region', country ?? 'unknown');
    res.headers.set('x-checkout-ratelimit-remaining', remaining.toString());
    return res;
  } catch (err) {
    // Edge middleware error handling: Log and redirect to error page
    console.error('[CheckoutMiddleware] Error:', err);
    return NextResponse.redirect(new URL('/checkout/error', req.url));
  }
}

// Next.js 16: Configure middleware matcher for checkout routes
export const config = {
  matcher: ['/checkout/:path*'],
};

// PaymentForm.tsx
// React 20 Client Component for checkout payment submission
// Uses concurrent rendering and useDeferredValue v2 for low-end device support
'use client';

import { useState, useDeferredValue, useTransition, useEffect } from 'react';
import { useCheckoutSession } from '@/providers/CheckoutSessionProvider';
import type { PaymentMethod, PaymentError, PaymentResponse } from '@/types/payment';

// Stripe Elements v12 (2026 compatible) for PCI-compliant payments
import { CardElement, useStripe, useElements } from '@stripe/react-stripe-js';
import { stripePromise } from '@/lib/stripe';

export default function PaymentForm() {
  const { session, isLoading: sessionLoading } = useCheckoutSession();
  const stripe = useStripe();
  const elements = useElements();
  const [paymentMethod, setPaymentMethod] = useState('card');
  const [isProcessing, setIsProcessing] = useState(false);
  const [paymentError, setPaymentError] = useState(null);
  const [paymentSuccess, setPaymentSuccess] = useState(false);
  // React 20: useDeferredValue v2 for non-urgent state updates (avoids UI jank)
  const deferredPaymentMethod = useDeferredValue(paymentMethod);
  // React 20: useTransition for concurrent state updates
  const [isPending, startTransition] = useTransition();

  // Handle payment method toggle with concurrent rendering
  const handlePaymentMethodChange = (method: PaymentMethod) => {
    startTransition(() => {
      setPaymentMethod(method);
    });
  };

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!stripe || !elements || !session) return;

    setIsProcessing(true);
    setPaymentError(null);

    try {
      // 1. Create payment intent via Next.js 16 API route (edge-deployed)
      const intentRes = await fetch('/api/checkout/create-payment-intent', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          sessionId: session.id,
          amount: session.totalAmount,
          currency: session.currency,
          paymentMethod: deferredPaymentMethod,
        }),
      });

      if (!intentRes.ok) {
        const errorData: PaymentError = await intentRes.json();
        throw errorData;
      }

      const { clientSecret } = await intentRes.json();

      // 2. Confirm payment with Stripe
      const cardElement = elements.getElement(CardElement);
      if (!cardElement) throw new Error('Card element not found');

      const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
        payment_method: { card: cardElement },
      });

      if (error) {
        throw error as PaymentError;
      }

      // 3. Update checkout session status
      const updateRes = await fetch('/api/checkout/update-status', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          sessionId: session.id,
          status: 'paid',
          paymentIntentId: paymentIntent.id,
        }),
      });

      if (!updateRes.ok) throw new Error('Failed to update session status');

      setPaymentSuccess(true);
    } catch (err) {
      const error: PaymentError = {
        code: 'PAYMENT_FAILED',
        message: err instanceof Error ? err.message : 'Unknown payment error',
        timestamp: new Date().toISOString(),
      };
      setPaymentError(error);
      console.error('[PaymentForm] Payment failed:', error);
    } finally {
      setIsProcessing(false);
    }
  };

  if (sessionLoading) return Loading session...;
  if (!session) return No active checkout session;
  if (paymentSuccess) return Payment successful! Redirecting...;

  return (

      Payment Details

         handlePaymentMethodChange('card')}
          disabled={isPending}
        >
          Credit Card

         handlePaymentMethodChange('apple_pay')}
          disabled={isPending}
        >
          Apple Pay


      {deferredPaymentMethod === 'card' && (



      )}
      {paymentError && (

          {paymentError.message}

      )}

        {isProcessing ? 'Processing...' : `Pay ${session.totalAmount} ${session.currency}`}


  );
}

// ProductDetails.server.tsx (React 20 Server Component)
import { cookies } from 'next/headers';
import { getProduct } from '@/lib/shopify';

export default async function ProductDetails({ productId }: { productId: string }) {
  // RSCs can be async — no useEffect needed
  const cookieStore = cookies();
  const sessionToken = cookieStore.get('shopify_checkout_session')?.value;
  const product = await getProduct(productId, sessionToken);
  return (

      {product.title}
      {product.description}
      Price: {product.price} {product.currency}

  );
}

// Rate limit check snippet from middleware.ts
const { success, remaining } = await ratelimit.limit(ip);
if (!success) {
  return NextResponse.json(
    { error: 'Too many requests' },
    { status: 429, headers: { 'Retry-After': reset.toString() } }
  );
}

// useDeferredValue v2 example from PaymentForm.tsx
const [paymentMethod, setPaymentMethod] = useState('card');
// Defer non-urgent payment method UI updates
const deferredPaymentMethod = useDeferredValue(paymentMethod);

// Use deferred value in render instead of raw state
{deferredPaymentMethod === 'card' && }