Shopify Storefront API for Custom Frontends

By Kokil Thapa | Last reviewed: September 2026

You want a custom storefront that does not look like every other Shopify theme. The Shopify Storefront API for custom frontends is how you get there. It exposes catalog, cart, and checkout data over GraphQL so your Vue app, Laravel Blade site, or static site can sell products while Shopify handles inventory and payments. I've used it on international florist builds and on WooCommerce and Shopify eCommerce projects where the client needed a branded experience outside Liquid. This guide covers auth, queries, cart flow, stack choices, and the production mistakes that break launches.

What Is the Shopify Storefront API for Custom Frontends?

The Storefront API is Shopify's customer-facing GraphQL layer. It sits beside the Shopify Admin API, but the two APIs serve different jobs. Admin API manages products, orders, and settings from your backend. Storefront API serves buyers on the web.

Every response is GraphQL. You request only the fields you need. That keeps payloads small on mobile networks, which matters for Nepal buyers on 4G. The API version follows Shopify's quarterly release cycle. Pin to 2026-07 or later in production so you are not running stale schemas.

A headless setup typically looks like this: your frontend talks to Storefront API, Shopify hosts checkout, and optional middleware handles webhooks through Admin API. You do not rebuild payment processing. You rebuild the shopping experience.

Storefront API access is scoped to unauthenticated buyer actions plus cart management. It cannot delete products or refund orders. That boundary is intentional. You can safely expose the Storefront token in browser code. Never expose Admin API credentials the same way.

What the API exposes

• Catalog: products, collections, variants, metafields, and search
• Cart: create cart, add lines, update quantities, apply discount codes
• Checkout: cart returns a checkoutUrl for hosted payment
• Customer: login and account data when using customer access tokens
• Localization: markets, currencies, and translated content

If you need full order management from your app, pair Storefront API with Admin API on a secure server. That pattern mirrors headless Magento REST setups where storefront and admin layers split cleanly.

How Do You Authenticate and Configure the Storefront API?

Setup starts in Shopify Admin. Create a custom app or use the Headless channel. Shopify generates a Storefront API access token and your shop domain. Those two values are enough for read-only catalog calls.

For cart mutations from the browser, also note the API version path. Requests go to a single endpoint:

POST https://{shop}.myshopify.com/api/2026-07/graphql.json
Content-Type: application/json
X-Shopify-Storefront-Access-Token: {your_public_storefront_token}

{
  "query": "{ shop { name } }"
}

Official docs live at shopify.dev/docs/api/storefront. Bookmark the version picker. Breaking schema changes arrive every quarter.

Step-by-step app setup

1. In Shopify Admin, open Settings → Apps and sales channels → Develop apps.
2. Create an app and enable Storefront API scopes you need: unauthenticated_read_product_listings, unauthenticated_write_checkouts, and related cart scopes.
3. Install the app on your store and copy the Storefront access token.
4. Store the token in frontend env vars such as VITE_SHOPIFY_STOREFRONT_TOKEN for Vite 8.x builds.
5. Pin API version 2026-07 in your client wrapper so upgrades are deliberate.

On a production Laravel or Node proxy, you can hide the token behind your own API layer. That adds rate-limit control and logging. Direct browser calls are simpler and officially supported for Storefront tokens.

Use the JSON formatter when debugging responses during development. GraphQL errors often return HTTP 200 with an errors key. Treat that as a failed call.

How Do You Build Product Pages and Cart Flows with GraphQL?

Product listing starts with a collection or search query. Request handles, prices, and variant IDs. The variant ID is what cart mutations require. Slugs alone are not enough.

Fetch a product by handle

query ProductByHandle($handle: String!) {
  product(handle: $handle) {
    title
    descriptionHtml
    featuredImage { url altText }
    variants(first: 20) {
      edges {
        node {
          id
          title
          price { amount currencyCode }
          availableForSale
        }
      }
    }
  }
}

Cache product pages aggressively at the CDN layer. Catalog data changes less often than cart state. Use short TTLs or webhook-driven revalidation if you run a Vite 8.x static build.

Create a cart and add a line item

Cart state in modern Shopify headless flows uses the cartCreate and cartLinesAdd mutations. The API returns a cart ID and a checkoutUrl.

mutation CreateCart($lines: [CartLineInput!]!) {
  cartCreate(input: { lines: $lines }) {
    cart {
      id
      checkoutUrl
      lines(first: 10) {
        edges {
          node {
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
              }
            }
          }
        }
      }
    }
    userErrors { field message }
  }
}

Variables for the mutation look like this:

{
  "lines": [
    {
      "merchandiseId": "gid://shopify/ProductVariant/1234567890",
      "quantity": 1
    }
  ]
}

Persist the cart ID in localStorage or a cookie. Pass it to subsequent cartLinesAdd and cartLinesUpdate calls. Without persistence, every page refresh starts an empty cart. That bug shows up constantly on first headless builds.

Markets, currency, and Nepal checkout notes

Multi-currency stores need the @inContext directive or country headers so prices match the buyer's market. On stores selling to Nepal, confirm whether NPR is enabled as a presentment currency. Payment methods still depend on Shopify Payments availability and third-party gateways.

Local gateways like eSewa and Khalti are not native Shopify Checkout options. A common pattern is a hybrid: catalog and cart on headless frontend, then a custom payment step via Shopify custom payment integrations or an external Laravel cart for domestic-only flows. Know that limitation before you promise a fully headless NPR checkout.

For international card checkout, redirecting to checkoutUrl is the path of least resistance. Shopify calculates tax and shipping inside checkout. Your frontend does not reimplement that logic.

How Does the Storefront API Compare to Hydrogen and Liquid Themes?

You have three realistic frontend paths. Each fits a different team and budget. None is universally best.

Read the dedicated Hydrogen vs custom React storefront comparison if React is already your stack. Hydrogen wraps Storefront API with routing, caching, and Oxygen deploy conventions. A custom frontend uses the same API with your own conventions.

On florist eCommerce builds, Liquid plus heavy customisation often ships faster than full headless. Headless earns its cost when marketing needs a distinct UX, a separate mobile web app, or content from a CMS outside Shopify.

Liquid themes still benefit from custom Liquid development when you stay in-theme. Storefront API is the escape hatch when the theme model itself is the bottleneck.

What Are Common Production Mistakes with Headless Shopify?

Headless Shopify fails in predictable ways. Most are fixable before launch if you plan for them.

Rate limits and query cost

Storefront API uses a calculated query cost bucket, not simple request counts. Deep nested queries burn capacity fast. Flatten product lists. Paginate with cursors. Avoid fetching entire catalogs in one query during SSR.

Shopify documents rate limits in the API usage and rate limits guide. Log query cost headers in staging so you see spikes before traffic does.

SEO and indexation

Headless frontends own URL structure, meta tags, and Core Web Vitals. Shopify's theme SEO defaults disappear. You must render canonical tags, product schema, and sitemaps yourself or through your framework.

That work belongs in the architecture phase, not the week before launch. Pair frontend work with technical SEO review if organic search drives revenue.

Stale inventory and webhooks

Storefront API reads live inventory at query time, but aggressive CDN caching can show sold-out variants. Use shorter cache for PLP cards or listen to inventory_levels/update webhooks via Admin API to purge cache keys.

Mixing Admin and Storefront concerns

A common mistake is calling Admin API from the browser to "fix" missing Storefront fields. That exposes private tokens and violates Shopify policy. If data is missing from Storefront API, expose it via metafields with Storefront visibility, or fetch it server-side.

The GraphQL spec's error handling rules are documented at graphql.org/learn/response. Partial data plus errors is valid GraphQL. Your UI must handle both.

Deployment and preview environments

Point staging frontends at a Shopify development store. Never run cart tests against production with real payment methods enabled. For teams using GitLab CI like my Deployer pipelines on legal-tech sister sites, store tokens in CI variables and inject at build time.

Performance tuning belongs in the same pass as launch. Compress images, lazy-load galleries, and measure LCP on 4G profiles. Speed optimisation on headless stacks is entirely yours to own.

Key Takeaways

• The Storefront API is public GraphQL for catalog, cart, and checkout handoff — pin version 2026-07 or later.
• Storefront tokens are safe in browser code; Admin API secrets stay on the server only.
• Persist cart IDs client-side and redirect to checkoutUrl for payment — do not rebuild checkout.
• Choose Liquid for speed, Hydrogen for React teams, or raw Storefront API when you need full UI control.
• Plan SEO, caching, rate limits, and Nepal payment constraints before you commit to headless architecture.
• Pair Storefront API with Admin API webhooks for order sync, inventory purge, and back-office automation.

People Also Ask

Is the Shopify Storefront API free to use?

Yes. Access is included with your Shopify plan. You pay your normal Shopify subscription and transaction fees. There is no separate API meter for Storefront calls beyond rate limits tied to your plan tier.

Can you use the Storefront API without Hydrogen?

Yes. Hydrogen is optional sugar on top of the same GraphQL endpoint. Any HTTP client in JavaScript, PHP, or mobile can call Storefront API directly with a valid token and versioned endpoint URL.

Does headless Shopify support NPR and local Nepal payments?

Presentment currency and markets are configurable, but local wallets like eSewa are not standard Shopify Checkout methods. Confirm currency support in Admin, then plan custom payment apps or a hybrid domestic checkout if NPR wallets are required.

What is the difference between Storefront API and Storefront MCP?

Storefront API is the stable GraphQL interface for building buyer-facing apps. Newer agent and AI commerce tools may expose higher-level helpers, but production custom frontends still rely on Storefront API mutations and queries documented on shopify.dev.

Ship Your Custom Storefront with the Right API Boundaries

The Shopify Storefront API for custom frontends gives you freedom on UI without giving up Shopify's checkout, inventory, and fulfillment core. Start with a pinned API version, a cart persistence strategy, and a honest read on payment and SEO ownership. Keep Admin API on the server for webhooks and private data.

If you want help scoping a headless build — or deciding whether Liquid is enough — review the portfolio of eCommerce work or reach out through contact us. For full build delivery, see e-commerce development services and related web development options on kokil.com.np.