Shopify Storefront API: The Complete Developer and Merchant Guide

The Shopify Storefront API is a public-facing GraphQL API that lets you build fully custom buying experiences, from headless storefronts and mobile apps to IoT and AI agent integrations, all while Shopify handles the commerce backend. Unlike the Admin API, it is designed to be called safely from browsers and mobile clients. If you are evaluating it for a project right now, the current stable version is 2026-04 and a 2026-07 release candidate is already available for testing.

Key takeaways

• The Storefront API is public-facing and safe to call client-side; the Admin API must stay on a secure server.
• Cart mutations (cartCreate, cartLinesAdd, cartBuyerIdentityUpdate) are the core write operations every build needs.
• API versions follow a quarterly cadence: 2026-01, 2026-04, 2026-07, 2026-10. The old 2024-10 version sunsets in October 2026.
• Hydrogen 2026.4.0 made the Storefront API proxy mandatory and enabled backend consent mode by default, two breaking changes that require an audit before upgrading.
• As of Hydrogen 2026.1.4, every Hydrogen storefront on Oxygen automatically exposes an MCP endpoint at /api/mcp, making it an AI-agent-ready commerce endpoint with zero custom code.

What is the Shopify Storefront API?

The Storefront API is Shopify's customer-facing GraphQL API. It gives developers read access to products, collections, metaobjects, and menus, plus write access for the two things buyers actually do: manage a cart and authenticate as a customer.

Here is how Shopify's own documentation frames its access model: the Storefront API is primarily read-only, with the exception of authentication and managing a cart. That boundary is intentional. You can fetch every product detail, build a live filter UI, and construct a full checkout flow without ever touching a secret credential.

The endpoint pattern is straightforward:

`` https://{your-store}.myshopify.com/api/2026-04/graphql.json ``

Every request needs a Shopify-Storefront-Public-Token header (or the private-token equivalent for server-side Hydrogen calls). The token is not secret and can be embedded in browser or mobile code. Your Admin API key and password, on the other hand, must never appear in client-side code.

Storefront API vs. Admin API: the real difference

This is the question every merchant and developer asks first, and the answer is architectural, not just a list of features.

The Admin API gives you complete read-and-write access to your Shopify store data: orders, customers, products, inventory, fulfillment, analytics, and more. The Storefront API intentionally lacks those administrative functions. You cannot modify orders, manage inventory, or access internal analytics through it. That is not a limitation to work around; it is the security boundary that lets you safely embed the token in a React component.

A common mistake: using Admin API credentials in client-side code. That exposes your shop credentials to the public. Always keep Admin API calls on a secure backend server. If you need client-side access to store data, that is exactly what the Storefront API is for.

Core capabilities: what you can actually build

Product and collection queries

Fetch product titles, descriptions, variant pricing, inventory status, images, and metafields. Because GraphQL lets you request only the fields you need, a product card query can return a lean 3-field response instead of a bloated REST payload. The speed and efficiency of only getting the data you ask for makes it ideal for performance-sensitive applications.

One important recent change: GraphQL product variants now support up to 2,000 per product, expanded from the previous 100-variant ceiling. If you sell configurable products (size x color x material), this matters.

Cart mutations

The Cart object is the heart of every Storefront API build. The current mutation surface includes:

• cartCreate, create a new cart and optionally add a line item in one call
• cartLinesAdd, add one or more product variants to an existing cart
• cartLinesUpdate, update quantity on existing lines (accepts up to 250 values per call)
• cartLinesRemove, remove lines by ID
• cartDiscountCodesUpdate, apply or clear discount codes (replaces all existing codes with the provided list)
• cartGiftCardCodesAdd / cartGiftCardCodesRemove, manage gift card redemption
• cartBuyerIdentityUpdate, associate a logged-in customer, set a B2B company location, or configure checkout preferences like delivery method
• cartMetafieldsSet, write arbitrary metafields onto the cart for custom checkout logic

A recent addition worth knowing: the CartLine type now returns a viewKey field, so you can correlate returned lines with the view_key sent to cartLinesUpdate and cartLinesRemove. Useful when you are building optimistic UI updates.

Privacy-compliant consent

Since Storefront API version 2025-10 and onwards, the @inContext directive accepts a visitorConsent argument. This lets you encode consent state directly into the cart creation call and have it automatically included in the resulting checkoutUrl. The result: GDPR and CCPA compliance flows without a separate cookie-writing layer.

Metaobjects and token-gated access

Some features require token-based authentication beyond the public access token. Product tags, metaobjects, metafields, store navigation menus, and customer data all sit behind token-scoped access. Requesting these scopes is done when you create the Storefront API app in the Shopify admin.

API versioning: what merchants and developers need to track

Shopify's Storefront API follows a quarterly release cadence: versions are named 2026-01, 2026-04, 2026-07, and 2026-10. Each version is supported for 12 months after release. Calls to unsupported API versions will result in apps being delisted or blocked from installing.

Right now the key dates are:

• 2026-04 is the current stable (latest) version.
• 2026-07 is the release candidate, tied to Shopify's Summer 2026 Edition (codename Compass), which ships 65 product updates including breaking changes to cart and product query structures.
• 2024-10 sunsets in October 2026. If your headless build is still on that version, you have a finite runway to migrate.

The 2026-07 breaking changes affect every headless build, Hydrogen, Next.js Commerce, Nuxt, or fully custom. Shopify provides codemods for Hydrogen projects to automate the query migrations.

For merchants evaluating whether to act now: if you are running a custom headless build on any version older than 2025-04, schedule a version audit with your developer this quarter. See our Shopify developer services page for what a version audit typically involves.

The Hydrogen connection: Storefront API proxy is now mandatory

Hydrogen is Shopify's React-based framework built directly on top of the Storefront API, and in 2026 the relationship between the two got significantly tighter.

Hydrogen 2026.4.0 (shipped April 17, 2026) introduced two breaking changes:

1. The Storefront API proxy is now always enabled. The proxyStandardRoutes configuration option was removed. If a request handler runs without a storefront instance in its load context, it throws a runtime error. Any custom Hydrogen setup that bypassed the proxy needs to be updated.
2. Backend consent mode is now the default. Hydrogen no longer relies on the client-side _tracking_consent cookie. Consent is now managed through server-set cookies written via the Storefront API proxy. Custom consent banners that read document.cookie for _tracking_consent will see an empty value after upgrading.

The reason these two changes are coupled: the whole point of backend consent mode is that consent writes cannot silently fail when a proxy is missing. The proxy becoming mandatory was the prerequisite.

If you run a custom Hydrogen setup (any project that is not a clean create-hydrogen skeleton), audit your createRequestHandler calls and consent banner logic before upgrading to 2026.4.x.

The biggest shift in 2026: your storefront is now an AI agent endpoint

This is the development that changes the Storefront API's role most fundamentally.

Hydrogen 2026.1.4 added built-in Storefront MCP (Model Context Protocol) proxy support. Every Hydrogen store on Oxygen now exposes an MCP endpoint at /api/mcp with zero custom setup. What that means in practice: AI assistants like ChatGPT, Perplexity, and custom shopping agents can discover your products, manage carts, and guide buyers through checkout using natural language, all powered by real-time data from the Storefront API.

Shopify exposes three distinct MCP surfaces:

• Catalog MCP, global product discovery across Shopify merchants
• Storefront MCP, merchant-specific search, policies, and FAQs
• Checkout MCP, programmatic cart creation, updates, and checkout completion

Public product discovery through Storefront MCP does not require additional authentication. Authenticated cart operations use the existing Shopify-Storefront-Private-Token header your Hydrogen app already sends.

To verify the proxy is active on your store: hit /api/mcp on your Oxygen deployment. If it forwards to Shopify's Storefront MCP server, you are live.

For merchants not yet on Hydrogen, this is a concrete reason to evaluate the migration. Liquid themes on Shopify's CDN deliver consistent but fixed performance. Hydrogen on Oxygen delivers that performance baseline plus AI agent integration without degradation. The ROI calculation for AI commerce features is shifting in Hydrogen's favor. You can explore what a Hydrogen migration involves on our Shopify headless developer page.

Practical checklist for merchants and developers

If you run a Hydrogen storefront:

• Confirm you are on Storefront API 2026-04 (the current latest)
• Audit createRequestHandler for the now-removed proxyStandardRoutes option
• Check your consent banner reads server-set cookies, not _tracking_consent
• Test /api/mcp on your Oxygen deployment to confirm MCP is active
• Start testing against the 2026-07 release candidate now; do not wait for October

If you run a custom headless build (Next.js, Nuxt, etc.):

• Identify your current API version and map it against the October 2026 sunset of 2024-10
• Review the 2026-07 changelog for breaking changes to cart and product query structures
• Plan codemods or manual query updates before the next Shopify Editions cycle

If you run a standard Liquid theme:

• The Storefront API is still relevant if you use any third-party app that calls it client-side
• Verify those apps are targeting 2026-04 or newer
• Consider whether the AI agent capabilities in Hydrogen justify a migration evaluation

The Storefront API is no longer just the "headless Shopify" API. It is the data layer that connects your catalog to every surface a buyer might use, browser, mobile, voice, and now AI agents. Keeping your version current and your Hydrogen setup aligned with Shopify's proxy and consent requirements is the maintenance work that keeps those surfaces open.