Shopify Storefront API: Complete Guide for Custom Frontends

Why Storefront API Matters

Shopify's default Liquid theme has limits. You can't run custom business logic before checkout, integrate proprietary systems, build mobile apps, or A/B test checkout flows.

Storefront API untethers you. Build any frontend (React, Vue, Next.js, Swift, Kotlin), and Storefront API is your data layer.

Architecture:

Custom Frontend (React, Next.js, SwiftUI, Kotlin)
    ↓
Storefront API (GraphQL endpoint)
    ↓
Shopify Product Catalog, Cart, Checkout

Your frontend handles UI/UX. Storefront API handles data. Shopify handles payments and fulfillment.

Core Domains

1. Product Catalog: - Fetch products, collections, variants - Search, filtering - Descriptions, images, metafields - Pricing, inventory

2. Shopping Cart: - Create/manage carts - Add/remove items - Apply discounts - Calculate totals

3. Checkout: - Redirect to Shopify-hosted checkout - Or: custom checkout UI via Payment Session API - Payment processing - Order confirmation

4. Customer Accounts: - Registration, login - Order history - Address book - Metafields (loyalty, preferences)

Authentication

Storefront API uses public access token. You embed it in frontend code—it's public and intended to be visible.

Getting your token:

Admin → Settings → Apps and integrations → Develop apps → Create app → Storefront API → Get token

Example: 90a5dfe05afef8c4e5f7c6d5b8e4a1c2

Include in every request:

X-Shopify-Storefront-Access-Token: token

Use GraphQL clients (Apollo, TanStack Query) to handle headers automatically.

Building Your Product Catalog

Fetch single product:

Query product by handle, get title, description, pricing, variants, images, metafields.

Fetch collection:

Query collection by handle, get products in that collection.

Search products:

Query with keyword filter, get matching results.

All queries are cacheable. Cache for 5-10 minutes to reduce API calls by 90%.

Managing Carts

Create cart:

Mutation to create cart with initial line items. Returns cart ID and checkout URL.

Add to cart:

Mutation to add items to existing cart.

Apply discount:

Mutation to apply discount code to cart.

Redirect to checkout:

After cart is ready, redirect customer to checkoutUrl.

Checkout: Two Paths

Path 1: Redirect to Shopify Checkout (Simpler)

After creating cart, redirect to checkoutUrl.

Pros: - Shopify handles payment processing - PCI compliance built-in - No fraud risk

Cons: - Leave your domain - Limited customization

Path 2: Custom Checkout (More Control)

Build your own checkout UI using Payment Session API.

Pros: - Stay on your domain - Full customization - Custom business logic

Cons: - Complex (requires backend) - PCI compliance responsibility - Higher fraud risk

Recommendation: Start with Path 1 (redirect to Shopify checkout). Only build custom checkout if you have specific business logic.

Customer Authentication

Create customer account:

Mutation with first name, last name, email, password.

Fetch customer's orders:

Query with customer access token. Returns customer's order history.

Store customer token securely:

httpOnly cookie (web) or secure keychain (mobile). Never expose in frontend.

Real-World Architecture

Tech stack: - Frontend: Next.js (React) - Backend: Node.js API (optional) - Storefront API: Shopify GraphQL - Payment: Shopify Payments (checkout redirect) - Auth: Customer access tokens

Flow:

1. User browses → Frontend calls Storefront API
2. User adds to cart → cartCreate / cartLinesAdd mutations
3. User checks out → Redirect to checkoutUrl
4. Order confirmation → Shopify sends email
5. User views order → Fetch via Storefront API with token

Performance Optimization

Problem: Calling Storefront API for every product fetch is slow and risky for rate limits.

Solution 1: Cache results

Use React Query or SWR with 5-10 minute cache. Products don't change frequently.

Solution 2: Batch queries

Fetch 20 products in one query vs. 20 separate queries. Reduces API calls from 20 to 1.

Solution 3: CDN for static assets

Cache product images on CDN. Use srcset for responsive images.

Result: Reduce API calls by 80-90%.

Error Handling

Storefront API can fail. Plan for fallbacks:

Try to fetch product. If error, return cached data or placeholder. Log error for debugging.

Implement retry logic with exponential backoff for transient errors.

Tech Considerations

For high-traffic sites (1M+ monthly visitors), use server-side rendering (Next.js), aggressive caching, and CDN. Most high-traffic sites cache product data for 5-10 minutes.

---

Frequently Asked Questions