The Shopify Storefront API is the foundation for every headless Shopify storefront. It gives developers read and write access to products, cart, checkout, and customer data via GraphQL — completely outside Shopify’s Liquid theme system. If you’re building a custom storefront, a mobile app, or a multi-channel commerce experience, the Shopify Storefront API is the connection between your front-end and Shopify’s commerce engine.
Key Takeaways
- The Storefront API uses GraphQL and is the correct API for front-end and customer-facing operations — not the Admin API
- Authentication uses public or private access tokens issued via the Headless sales channel in Shopify Admin
- Each stable API version is supported for at least 12 months, so 2024-10 is already unsupported — any apps or storefronts still on it should move to a supported version such as 2026-07 or later
- The Storefront API is available on all paid Shopify plans; most advanced headless use cases benefit from Shopify Plus
What Is the Shopify Storefront API and What Can It Do?
The Storefront API is a public-facing GraphQL API that allows you to build custom shopping experiences. Unlike the Admin API — which requires authentication and gives access to store management, orders, and sensitive data — the Storefront API is designed for customer-facing interactions.
It handles product display, collection browsing, cart creation and management, checkout initiation, and customer account operations. It does not expose pricing overrides, fulfillment data, or store configuration — those belong to the Admin API.
GraphQL vs REST — Why Shopify Chose GraphQL
The Shopify Storefront API has been GraphQL-only since its introduction. This means you request exactly the fields you need in a single query, rather than calling multiple REST endpoints and filtering responses client-side.
For a product page, for example, you can fetch the product title, selected variant price, inventory status, images, and metafields in a single request. REST would require two or three separate calls. The payload is smaller, the latency is lower, and the response shape matches exactly what your UI needs.
The trade-off: GraphQL has a higher learning curve than REST for developers unfamiliar with it. Tools like GraphiQL (Shopify’s built-in API explorer in the Admin) help significantly.
What the Storefront API Can (and Cannot) Do
Can do:
- Query products, variants, collections, metafields, and metaobjects
- Create and manage shopping carts (Cart API)
- Initiate checkout (hand-off via
cart.checkoutUrl) - Authenticate and manage customer accounts (Customer Account API)
- Handle multi-currency pricing and international market configurations
- Support predictive search and product filtering
Cannot do:
- Access or modify orders after they’re created (use Admin API)
- Modify product data, pricing, or inventory
- Access staff, shipping zones, or fulfillment configurations
- Perform store management operations of any kind
Say a developer is building a Next.js storefront for a specialty coffee brand. The store sells in the US, UK, and Germany with different currencies. Using the Storefront API, the developer fetches product listings with localized pricing in a single GraphQL query, passing the buyer’s country code as a context variable. What would have taken multiple API calls and client-side calculation is one request returning correctly formatted, currency-adjusted prices. The checkout hand-off is seamless because Shopify handles localized taxes and duties automatically at the checkout level.
Getting Access: Authentication and Tokens
Public vs. Private Access Tokens
The Storefront API uses access tokens, not OAuth. There are two types:
Public access tokens are embedded in your front-end code. They’re scoped to read-only Storefront API operations. Anyone who views your source code can see this token — that’s acceptable because it only allows what a public storefront can do anyway.
Private access tokens are used from a server or other private context, like a Hydrogen backend, where the token must stay secret. The Headless channel issues one alongside the public token; a custom app can instead create a delegate access token for the same server-side use.
Never use the Admin API access token in a client-side or public context. The Admin API token gives full store access — exposing it is a serious security issue.
Installing the Headless Channel in Shopify Admin
To generate a Storefront API access token:
- In Shopify Admin, go to Settings → Apps and sales channels
- Open the Shopify App Store and search for “Headless”
- Install the Headless sales channel
- In the Headless channel, create a new storefront and copy the Storefront API access token
This is the recommended path as of 2026. Older documentation references creating tokens through private apps — that method is deprecated.
Core Capabilities of the Shopify Storefront API
Product and Collection Queries
Product queries return the full product object including all variants, images, metafields, and pricing. You can query a single product by handle or ID, or query collections with pagination.
The key addition in recent API versions is metaobjects — custom structured data types you can define in Shopify Admin and query via the Storefront API. This enables things like custom size guide content, brand story sections, and specification tables to be managed through Shopify and surfaced in your custom storefront.
Cart and Checkout Operations
The Cart API replaced the older Checkout API for most use cases. You create a cart with cartCreate, add items with cartLinesAdd, apply discounts with cartDiscountCodesApply, and obtain a checkout URL via cart.checkoutUrl.
The checkout itself is handled by Shopify — your storefront hands off to Shopify’s hosted checkout. This means Shopify’s payment processing, 3DS authentication, and fraud detection all work without custom integration.
Customer Account API Integration
The Customer Account API (separate from the legacy Storefront API customer authentication) launched in 2024 and has become the recommended way to handle customer login and account management in headless storefronts. It uses OAuth 2.0 authorization code flow with PKCE.
For merchants on Shopify Plus, the Customer Accounts new interface can be configured and extended. For standard plans, the default customer account experience is used.
Multi-Currency and International Markets Support
The Shopify Storefront API supports Shopify Markets natively. Passing a @inContext directive with a country code adjusts pricing, currency formatting, and product availability to the configured market rules. A store configured with Shopify Markets returns locally relevant prices without any custom conversion logic on your end.
2026 API Changes You Need to Know
Version 2026-07 Breaking Changes
The July 2026 API version introduced structural changes to cart and product query responses. Specifically:
- The
cartobject response structure for line item attributes was reorganized - Several deprecated fields that were still functional in 2024-10 were fully removed
If you’re building on Hydrogen or a custom stack, always pin to an explicit API version in your requests. Relying on the “unstable” version in production is how breaking changes cause outages.
Old 2024-10 Version: Already Unsupported
Shopify supports each stable API version for at least 12 months, so the 2024-10 Storefront API version is no longer supported. Requests to an unsupported version don’t simply fail: Shopify falls forward and responds using the oldest supported stable version, which can change response shapes without warning.
If you’re maintaining a headless storefront or app built before mid-2025, check which API version your GraphQL client is targeting. The X-Shopify-API-Version header in requests will tell you. Migration to 2026-07 is not trivial — run a full test cycle against the new version before you switch.
Cart and Product Query Structure Changes
The 2026-07 changes are most likely to break stores that are using:
- The
checkoutmutation (deprecated — use Cart API instead) - Direct
availableForSalefield queries that don’t account for new inventory state fields - Custom cart attribute handling that relied on the previous structure
Shopify provides a changelog at shopify.dev with migration guides for each version. Reading it before you upgrade beats debugging production errors.
Building a custom Shopify storefront and need experienced development support? See our Shopify development services →
Using the Storefront API with Hydrogen vs. Custom Stacks
Hydrogen (React Router v7) — The Official Path
Hydrogen’s component library is built around the Storefront API. Queries for products, cart state, and customer data are first-class — there are pre-built hooks and utilities that reduce the boilerplate significantly.
If you’re building a headless storefront and your team is React-first, Hydrogen is worth serious consideration. The DX improvements over a raw GraphQL integration are real.
Next.js Commerce and Other Frameworks
Vercel maintains Next.js Commerce as an alternative starter for Shopify headless builds. It’s more opinionated about the Next.js App Router model and less tied to Shopify-specific utilities. Some teams prefer it for familiarity.
The Storefront API itself is framework-agnostic. It works the same whether you’re using React, Vue, Svelte, or a mobile SDK. Choose your framework based on your team’s expertise, not on Shopify’s preference.
Pure Custom Implementation
For mobile apps (React Native, Flutter, Swift, Kotlin), the Storefront API is the standard integration path. Shopify’s Mobile Buy SDK wraps the Storefront API for iOS and Android development.
For non-JavaScript environments, the API accepts standard HTTP POST requests with a JSON-encoded GraphQL query body. Language doesn’t matter — the API contract is the same.
Imagine a B2B kitchenware brand building a custom buyer portal using the Storefront API alongside a React Native mobile app. The portal shows trade pricing (configured through Shopify Markets with customer account context), allows bulk ordering via cart mutations, and surfaces custom metafields for product specifications. The Admin API handles order history display on the back-end. The Storefront API handles everything the buyer sees and touches. For wholesale buyers used to ordering from a PDF price list, that is a much faster way to place an order.
Conclusion
The Shopify Storefront API is the correct tool for any headless Shopify build. It handles everything customer-facing through a clean, versioned GraphQL interface. Understanding the boundary between the Storefront API and the Admin API — and staying current on version changes — is the difference between a stable headless storefront and a maintenance problem.
For the 2026 cycle, the two priorities are clear. Move anything still on 2024-10 to a supported version now. Build on 2026-07 with explicit version pinning so future API changes are controlled, not accidental.
Frequently Asked Questions
Is the Shopify Storefront API free to use?
Yes. There is no per-request cost for using the Storefront API. It is included with all paid Shopify plans. Your cost is development time, not API access fees.
Does the Storefront API have rate limits?
Requests from real buyers aren’t subject to a fixed requests-per-minute limit. Shopify applies bot and crawler protection and throttles how many checkouts can be created per minute, and tokenless access has a query complexity limit of 1,000. For most storefronts, none of this is a practical constraint.
Can I use the Storefront API without Shopify Plus?
Yes. The Storefront API is available on all paid plans (Basic and above). Some features that the API exposes — such as custom B2B pricing and advanced checkout extensibility — require Shopify Plus to configure in the Admin, but the API itself is not Plus-restricted.
What’s the difference between the Admin API and the Storefront API?
The Admin API requires server-side authentication (your private token never goes to a browser) and provides access to the full store backend: orders, customers, products, inventory, staff, and configuration. The Storefront API is public-facing, uses a scoped access token, and is limited to customer-facing operations. Use the Storefront API for anything a customer sees. Use the Admin API for anything a store manager sees.
How do I handle authentication for logged-in customers?
Use the Customer Account API, which is separate from the Storefront API. It handles OAuth-based customer login and returns a customer access token. That token is then passed in the customerAccessToken header on Storefront API requests that require authentication — such as accessing order history or managing saved addresses.