Shopify Storefront API: Guide and Agentic Storefronts Comparison

Shopify Storefront API is Shopify's GraphQL API for building custom customer-facing commerce experiences. Developers use it to query products and collections, create carts, power custom storefronts, and send shoppers into checkout.

That makes it important for headless commerce, mobile apps, product configurators, custom discovery experiences, and any frontend that needs Shopify commerce data without using a standard Shopify theme.

It is not the same thing as Shopify Agentic Storefronts. Storefront API helps you build the owned shopping experience. Agentic Storefronts help eligible products appear in AI shopping channels such as ChatGPT, Google AI Mode, Gemini, and Microsoft Copilot.

The practical question is not "Which one replaces the other?" It is: what do you need to build, what data does that surface need, and how will your products be understood outside your own storefront?

The short answer#

Use Shopify Storefront API when you need a custom storefront, app, or commerce interface that reads from Shopify and lets shoppers browse products, add items to cart, and check out.

Use Shopify Agentic Storefronts when you want eligible products to be discoverable and purchasable inside supported AI shopping channels.

Use Catalog when you need the product data layer underneath both paths to be richer, cleaner, more complete, and more portable across AI surfaces.

What Shopify Storefront API is#

Shopify Storefront API is a GraphQL API for creating customer experiences on any platform, including the web, apps, and games. Shopify says the API lets customers view products and collections, add products to a cart, and check out.

In plain terms, Storefront API is the customer-facing commerce API for Shopify.

It is commonly used for:

• Headless Shopify storefronts.
• Mobile commerce apps.
• Product discovery, filtering, and search interfaces.
• Custom product detail pages and collection pages.
• Bundles, configurators, quizzes, and guided shopping flows.
• Content-commerce experiences where Shopify powers products, carts, and checkout behind a custom frontend.
• Frontends built with Hydrogen, another JavaScript framework, or a fully custom stack.

The API is separate from the Shopify Admin API. Storefront API is for customer-facing commerce experiences. Admin API is for store management operations such as products, orders, customers, inventory, apps, and merchant back-office workflows.

That distinction matters. Do not expose Admin API credentials in a public storefront. A custom storefront should use Storefront API access with the right scopes for the customer-facing data and actions it needs.

How Shopify Storefront API works#

Storefront API uses GraphQL. Instead of calling many REST endpoints, a frontend sends a GraphQL query to Shopify and asks for the exact product, collection, cart, customer, or metaobject fields it needs.

A typical setup has four parts.

1. Storefront API access token#

A custom storefront uses a Storefront API access token. Many teams casually call this a Shopify Storefront API key, but Shopify's Storefront API authentication documentation usually describes it as an access token.

That token is used with requests to the Storefront API. It should not be confused with a private Admin API token. Shopify's official docs are the right next step for the current token-creation flow and supported authentication headers before you wire a production storefront.

2. GraphQL endpoint#

Storefront API requests go to a Shopify GraphQL endpoint for a specific shop and API version. Shopify documents the current endpoints and queries on the Storefront API reference; the production pattern is to call the versioned GraphQL endpoint for the shop with the Storefront API token in the request headers.

Versioning matters because Shopify releases new API versions. A production storefront should pin an API version, monitor deprecations, and plan upgrades instead of relying on whatever happens to be latest.

3. Queries and mutations#

Queries read data. Mutations change or create customer-facing commerce state.

Common Storefront API reads include:

• Products.
• Product variants.
• Collections.
• Search results.
• Metaobjects.
• Selling plans.
• Product availability.

Common Storefront API actions include:

• Creating a cart.
• Adding or removing cart lines.
• Updating quantities.
• Applying discount codes or buyer identity where supported.
• Sending the buyer into checkout.

For example, Shopify's Storefront API products query returns a paginated product list. It can support filters for availability, product type, tags, variants, vendor, updated dates, and other product fields. That is why the API is useful for custom collection pages, search interfaces, product grids, and filtering.

A simplified product query might look like this:

query ProductsForStorefront($first: Int!) {
  products(first: $first) {
    nodes {
      title
      handle
      description
      featuredImage {
        url
        altText
      }
      variants(first: 10) {
        nodes {
          title
          availableForSale
          price {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

The exact query you use depends on the storefront experience you are building. A lightweight landing page may only need product titles, images, handles, prices, and availability. A comparison tool may need variants, metafields, product options, media, collections, tags, selling plans, and custom data.

4. Frontend application#

The frontend turns Storefront API responses into the shopping experience. Shopify offers Hydrogen, its React-based framework for headless commerce, and officially supported clients for different stacks. Teams can also build with their own framework if they handle data fetching, caching, routing, analytics, SEO, and checkout behavior correctly.

This is where Storefront API becomes valuable. It gives the development team control over the experience, while Shopify remains the commerce system behind the scenes.

What Storefront API is good for#

Storefront API is strongest when the merchant needs a controlled owned experience.

Headless storefronts#

A headless storefront separates the frontend from the Shopify backend. The store can use a custom frontend while Shopify continues to manage products, carts, checkout, payments, inventory, and commerce operations.

This is useful when a standard theme cannot support the experience the brand wants.

Custom product discovery#

Storefront API can power custom product grids, filters, search interfaces, quizzes, collections, and product detail pages. If your merchandising logic depends on product type, tags, variants, metafields, vendor, availability, or custom grouping, the API gives developers a way to query and assemble that experience.

Apps and embedded commerce#

The API can support mobile apps, in-game commerce, creator storefronts, content sites, and campaign microsites where products and carts still come from Shopify.

Performance and UX control#

A custom frontend gives teams more control over performance, routing, content modeling, personalization, experimentation, and analytics. Storefront API is the Shopify data layer that lets that frontend stay connected to products and checkout.

What Storefront API does not solve by itself#

Storefront API is powerful, but it is not a full AI commerce strategy by itself.

It does not automatically make a product easy for an AI assistant to understand. It does not decide which product is best for a shopper's prompt. It does not enrich thin product data, normalize inconsistent fields, or distribute the catalog across every AI surface where shoppers may ask for recommendations.

It can return product data, but the quality of that data still depends on what exists in Shopify and what the frontend queries.

If product titles are vague, descriptions are thin, variant data is confusing, metafields are unmapped, compatibility notes are buried in images, or return/shipping constraints are missing, Storefront API can expose those weaknesses as easily as it exposes the products.

That is why Storefront API and AI shopping readiness should be treated as related but different problems.

What Shopify Agentic Storefronts do#

Shopify Agentic Storefronts are about AI shopping distribution. Shopify's Agentic Storefronts documentation describes them as a way for customers to discover and purchase products in AI channels such as ChatGPT, Google AI Mode, Gemini, and Microsoft Copilot.

Catalog has a deeper guide to Shopify Agentic Storefronts for merchants who want the channel-by-channel view. The important distinction here is that Agentic Storefronts are not a headless frontend framework.

They are closer to an AI-channel participation path.

The same Shopify documentation says products can be made available to AI channels through Shopify Catalog or, for Google AI Mode and Gemini, through the Google & YouTube sales channel. Shopify also notes that Google AI Mode and Gemini support is early access and not available for all stores.

So while Storefront API asks, "How do we build a custom commerce experience?" Agentic Storefronts ask, "How do our products become discoverable and purchasable where AI assistants are shopping on behalf of customers?"

Storefront API vs. Agentic Storefronts#

Storefront API and Agentic Storefronts are not substitutes.

A merchant can use Storefront API and not be ready for AI shopping. A merchant can participate in Agentic Storefronts and still need Storefront API for a custom website or app.

Here is the simplest way to separate them:

• Storefront API is for owned surfaces you build and control.
• Agentic Storefronts are for supported AI shopping surfaces you do not fully control.
• Catalog is for the product data quality and distribution problem that sits underneath AI commerce.

If you are building a custom frontend#

Start with Storefront API. Decide whether to use Hydrogen, another frontend stack, or an existing site architecture. Define the product, variant, collection, cart, search, and checkout behavior the experience needs.

Then make sure the product data model supports that experience. If the frontend depends on product attributes, use-case labels, compatibility rules, materials, dimensions, care instructions, availability, bundles, or reviews, those details need to be structured somewhere the application can query.

If you are preparing for AI shopping channels#

Start with Agentic Storefronts eligibility and channel setup. Check which AI channels are available, what each channel requires, and how products are discovered.

Then audit the product data like an AI assistant would. The issue is not only whether a product is present. It is whether the product can be understood, compared, and recommended accurately for a shopper's specific need.

If you need both#

Many merchants will need both.

A brand may want a fast custom frontend for owned conversion and, at the same time, want products to appear in AI-mediated shopping journeys. In that case, Storefront API powers the owned experience, while Agentic Storefronts and a richer product data layer help with AI-channel visibility.

Product data is the shared bottleneck#

The Storefront API can query product fields. Agentic Storefronts can make eligible products available in AI channels. Neither path magically fixes weak product data.

AI shopping systems need structured product facts, not just a product page URL.

Useful product context can include:

• Accurate titles and descriptions.
• Variant availability and price freshness.
• Product options, sizes, colors, materials, dimensions, and compatibility.
• Use cases and shopper-fit signals.
• Product comparisons and alternatives.
• Reviews and common objections.
• Shipping, returns, subscriptions, restrictions, and regional availability.
• Images and visual attributes that a text-only description misses.
• Metafields, metaobjects, tags, and other custom Shopify data.

Shopify's Catalog and product discovery documentation says Shopify Catalog can list products with title, description, options, images, price, availability, and other key attributes structured for AI agents to parse. Shopify's product data mapping guidance also points to Catalog Mapping when important product data lives in custom fields such as metafields, metaobjects, tag prefixes, or product-title patterns.

That is important because many Shopify stores keep their best product context outside default fields. Fit notes, product education, bundle logic, compatibility rules, and comparison copy may live in custom data, apps, theme sections, PDFs, images, reviews, support docs, or merchandising spreadsheets.

If those facts are not mapped or structured, the product can be technically available through an API or channel and still be hard for an AI system to recommend correctly.

Where Catalog fits#

Catalog does not replace Shopify Storefront API. It does not require merchants to ignore Shopify's native AI channels.

Catalog fits around both as the product data layer for AI commerce.

Storefront API helps teams build owned commerce experiences. Agentic Storefronts help eligible products participate in Shopify-supported AI shopping channels. Catalog helps make product data richer, more complete, and more portable across AI surfaces.

Catalog connects to Shopify, ingests the catalog, enriches product facts, and structures the details AI systems need before they recommend products. The Catalog API is built for teams that need live, structured product data for commerce agents and product discovery systems. Catalog's API messaging emphasizes normalized product fields, live pricing, stock confidence, variant matching, review signals, image analysis, similar products, and product enrichment.

That matters because AI shopping is not limited to one native Shopify channel. Shoppers ask product questions in ChatGPT, Gemini, Claude, Perplexity, search results, marketplaces, affiliate tools, and future shopping agents that do not all read merchant data the same way.

A merchant can use Shopify's native paths and still need Catalog if they want broader AI visibility and better product understanding.

The strongest setup is layered:

1. Use Shopify as the commerce system of record.
2. Use Storefront API where you need custom owned experiences.
3. Use Agentic Storefronts where Shopify-supported AI channels are available and relevant.
4. Use Catalog to enrich, normalize, and distribute product context across AI shopping surfaces.

Storefront API implementation checklist#

If you are planning a Shopify Storefront API build, start with the technical basics and the product-data basics together.

Confirm the storefront job#

Do not start with the API call. Start with the experience.

Are you building a full headless storefront, a mobile app, a product finder, a configurator, a content-commerce page, or a campaign microsite? The answer determines which product fields, cart behavior, routing, SEO, analytics, and checkout flow you need.

Choose the frontend approach#

Hydrogen is Shopify's official React-based framework for headless commerce. It can be a good fit when the team wants Shopify-native headless tooling.

A custom stack can also work if the team is ready to own more decisions: data fetching, caching, routing, SEO, hosting, analytics, error handling, and deployment.

Set up access carefully#

Use Storefront API access for customer-facing experiences. Do not expose Admin API credentials in frontend code.

Give the storefront only the access it needs, document which API version it uses, and make token handling part of your security review.

Model product data before building UI#

The storefront can only render the data available to it. Before building templates, confirm where important data lives:

• Shopify product fields.
• Variants and options.
• Metafields.
• Metaobjects.
• Tags.
• Collections.
• Selling plans.
• Reviews or third-party app data.
• Shipping, returns, and policy information.

If important facts are only present in theme copy, images, PDFs, or support articles, the API may not return them in a reliable way.

Plan caching and freshness#

Product pages need to be fast, but prices, inventory, variants, and availability can change. Decide which data can be cached, which data must stay fresh, and how the storefront handles unavailable variants or changed carts.

Treat AI readiness as a separate layer#

A Storefront API build can improve the owned shopping experience, but AI assistants need richer product understanding. If AI shopping visibility matters, build a product data layer that can support both the storefront and external AI discovery.

FAQ#

What is Shopify Storefront API used for?#

Shopify Storefront API is used to build customer-facing commerce experiences on top of Shopify. Common uses include headless storefronts, mobile apps, product discovery flows, custom carts, collection pages, product detail pages, and checkout journeys.

Is Shopify Storefront API GraphQL?#

Yes. Shopify Storefront API is a GraphQL API. Developers write queries and mutations to read products, collections, carts, search results, customer-facing data, and related commerce objects.

How do I get a Shopify Storefront API key?#

Most teams mean a Storefront API access token when they say Storefront API key. The exact setup depends on the Shopify configuration and app or custom storefront approach. Use Shopify's current Storefront API authentication documentation for token creation and request authentication, and do not confuse the Storefront API token with a private Admin API token.

Is Shopify Storefront API free?#

Storefront API is included in Shopify's customer-facing development model, but a production build is not automatically free. The practical cost depends on the Shopify plan, build approach, hosting, development work, app architecture, and any third-party systems you use. Check Shopify's current plan and API documentation for eligibility and limits before planning a production build.

Is Shopify Storefront API the same as Agentic Storefronts?#

No. Shopify Storefront API is a GraphQL API for building custom customer-facing storefront experiences. Agentic Storefronts are Shopify's path for making eligible products available in AI shopping channels.

Do Agentic Storefronts replace headless commerce?#

No. Headless commerce and Agentic Storefronts solve different jobs. Headless commerce controls your owned storefront experience. Agentic Storefronts help supported AI channels discover and transact with Shopify products.

Do I need Storefront API to use Agentic Storefronts?#

Not necessarily. Agentic Storefront setup is tied to Shopify's channel and product discovery paths, not to building a custom Storefront API frontend. But many merchants may use both if they have a custom storefront and also want AI-channel visibility.

Is Shopify Catalog enough for AI shopping visibility?#

Shopify Catalog is an important native path for eligible products, but it is not the whole AI-commerce strategy. Shopify itself notes channel-specific paths, including Google & YouTube for Google AI Mode and Gemini. Merchants still need complete, mapped, current product data that AI systems can parse and use.

Where does Catalog fit if Shopify has native Agentic Storefronts?#

Catalog helps enrich and distribute product data beyond one storefront or native channel. It turns Shopify product data into richer machine-readable context for AI shopping surfaces such as ChatGPT, Gemini, Claude, Perplexity, and future commerce agents.

The bottom line#

Shopify Storefront API is the right tool when you need to build a custom customer-facing Shopify experience. It gives developers GraphQL access to the products, collections, carts, checkout, and commerce data needed for a headless storefront or custom app.

Agentic Storefronts solve a different problem: making eligible Shopify products available in supported AI shopping channels.

Catalog fits underneath the AI-commerce side of the equation. It helps turn Shopify product data into richer, more complete, more portable product context so products can be understood wherever AI shopping happens.

If your goal is only a custom frontend, start with Storefront API. If your goal is AI commerce, do not stop at the endpoint or the channel toggle. Make sure the product data itself is good enough to be chosen.