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 delegate access tokens installed via the Headless sales channel in Shopify Admin
- The 2024-10 API version sunsets in October 2026 — any apps or storefronts still on it must migrate to 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 and complete checkout flows
- 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
Jamie is a developer 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, she 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.
Delegate access tokens are generated programmatically for specific use cases — typically when a third-party app or service needs Storefront API access on behalf of your store. They have a configurable expiration and can be scoped to specific permissions.
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 - Product variant
priceobjects now return apresentmentPricefield as the primary field for localized pricing - 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 Sunset Timeline (October 2026)
The 2024-10 Storefront API version reaches end-of-life in October 2026. After that date, Shopify will return errors for requests made to that version.
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 sunset date.
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. See our Shopify solutions if you need help scoping a headless build.
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.
A B2B kitchenware brand launched 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. Development took 18 weeks. The result: their largest wholesale accounts place 40% more orders per quarter because the ordering experience is faster than the previous PDF price list workflow.
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. Migrate away from 2024-10 before October. Build on 2026-07 with explicit version pinning so future API changes are controlled, not accidental.
If you’re scoping a headless Shopify project and need an agency that understands both the technical requirements and the business case, our Shopify development services cover the full build. See our fixed-price Shopify packages for defined-scope projects.
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?
The Storefront API uses a calculated query cost system rather than a traditional requests-per-minute limit. Complex queries that request more data cost more of your rate limit bucket. The bucket refills over time. For most storefronts, this is not a practical constraint — it becomes relevant for very high-traffic stores making complex queries on every page load.
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.