Headless Commerce Architecture Explained

Understanding the Big Picture

Headless commerce involves several components working together. It might seem complex at first, but once you understand each part's role, the overall picture becomes clear.

Two APIs, Two Purposes

Shopify provides two main APIs, each serving different needs.

Storefront API (Customer-Facing)

This API handles everything customers do on your website. It uses GraphQL for efficient data fetching.

What it can do:

• Fetch product information (name, price, images, etc.)
• Get collection (category) listings
• Add/edit/remove cart items
• Create checkout sessions
• Handle customer login and registration

This API uses a publicly shareable access token. It's safe to call directly from the browser (customer's device).

Admin API (Back-Office)

This API handles administrative operations. It manages privileged operations like inventory updates and order management.

What it can do:

• Update inventory levels
• Retrieve and update order information
• Manage customer data
• Edit product metafields
• Create discount codes

This API uses a secret access token. It should only be called from server-side code (like Next.js API Routes), never exposed to browsers.

System Architecture Diagram

Let's visualize how everything connects.

Following the Data Flow

Let's trace what happens when a customer makes a purchase.

1. Viewing the Product List

Behind the scenes, product data was fetched from Storefront API at build time and saved as HTML.

2. Adding to Cart

Cart operations need real-time interaction, so we call the API directly instead of using static generation.

3. Checkout

Payment processing happens on Shopify's secure pages. We never handle credit card information on our servers—that's a security win.

ISR: Best of Both Worlds

Product prices and inventory can change anytime. But calling the API on every request would slow things down. That's where ISR (Incremental Static Regeneration) comes in.

How ISR Works

1. First visit: Serve cached page
2. After configured time (e.g., 60 seconds): Generate new page in background
3. Next visit: Serve the new page

Customers never wait, yet content stays fresh.

Setting Appropriate Intervals

Different pages need different refresh rates:

• Product detail pages: 60 seconds (prioritize inventory/price accuracy)
• Collection pages: 5 minutes (reflect new products)
• Homepage: 10 minutes (less frequent updates)

Shopify Hydrogen: Another Option

Shopify also offers "Hydrogen," their official headless framework. Built on Remix, it provides tighter Shopify integration.

Choose Hydrogen when:

• You want a Shopify-optimized experience
• You're starting a new project from scratch

Choose Next.js when:

• You have existing Next.js assets
• You want access to a broader ecosystem and community
• You plan to integrate with services beyond Shopify

In our project, we chose custom Next.js implementation to leverage existing assets.

Considerations for Implementation

Required Resources

• Frontend Engineers: React/Next.js experience necessary
• Infrastructure: Hosting service like Vercel
• Timeline: Minimum 1-2 months depending on scope

Operational Considerations

• Need to maintain both Shopify and Next.js
• Must set up deployment pipelines
• Troubleshooting becomes more complex

Cost Factors

• Shopify monthly fees (varies by plan)
• Vercel hosting costs (based on traffic)
• Development and maintenance labor

Wrapping Up

Headless commerce offers significant advantages in performance, design freedom, and scalability. However, it also brings complexity in development and operations.

Consider your project's scale, technical resources, and future plans when deciding if headless is right for you. Starting with a small proof-of-concept is always a good approach.