ProductHow it worksDocsBlogPricingSign inGet Framer Plugin
← Blog

Shopify GraphiQL App: Test Storefront Queries for Framer

When a Framer storefront shows the wrong price or a sold-out badge on a product that is in stock, the Shopify GraphiQL app settles the argument in about a minute. Install it, run the same Storefront API query your site runs, and read the raw JSON Shopify returns. If the data is correct in GraphiQL and wrong on the page, the bug is in your frontend or your plugin. If it is wrong in both, the problem is your Shopify data or your query.

GraphiQL is an in-browser editor for writing GraphQL queries and seeing the response immediately, with the store's full schema browsable in a side panel. It is not a dashboard and not a reporting tool. It is the one place you can ask Shopify a question with no frontend in between.

Which Shopify GraphQL explorer do you need for a Framer site?

The one that talks to the Storefront API, which is the endpoint a Framer storefront actually calls. This trips people up because most write-ups — and Google's own AI summary for this query — describe GraphiQL purely as an Admin API tool. For debugging a headless frontend, Admin API results can actively mislead you: the Admin API sees every product, while the Storefront API only sees what is published to the channel your tokens belong to.

There are two places to run queries, and the difference matters:

  • The hosted explorer at shopify.dev/graphiql/storefront-graphiql runs against Shopify's own demo shop and is a read-only demo. Good for learning the schema, useless for your store.
  • The installed app at shopify-graphiql-app.shopifycloud.com connects to your store. Install the Shopify GraphQL app by entering your .myshopify.com URL, then toggle the access scopes you need.

Use the second one against a development store or a client store you have permission to touch. Then paste in the exact query your Shopify catalog sync is sending.

Five symptoms and the query that diagnoses each

Lead with the query, not the theory. Each row below takes one visible symptom on the Framer site, gives you the query to paste into GraphiQL, and tells you what the answer rules out.

Symptom on the Framer site Query to run How to read the result
Wrong or stale price product(handle:"x"){ priceRange{ minVariantPrice{ amount currencyCode } } } Correct here means your frontend is caching. Note there is no price field on Product — only priceRange and compareAtPriceRange, so a plugin reading price gets nothing
Sold out when it is in stock product(handle:"x"){ availableForSale totalInventory variants(first:10){ nodes{ availableForSale } } } availableForSale is true if at least one variant can be sold. A true product with false variants means your page is bound to the wrong variant
A variant is missing product(handle:"x"){ variantBySelectedOptions(selectedOptions:[{name:"Size",value:"L"}]){ id } } null means no variant matches those exact option values. Check for a trailing space or a case mismatch in your Framer CMS field before blaming the API
Filters return the wrong set products(first:10, filters:{available:true, price:{min:10,max:50}}){ nodes{ handle } } Different filters combine with AND, repeats of one filter with OR. If you send two price ranges, everything but the first range is ignored
Product missing entirely product(handle:"x"){ onlineStoreUrl publishedAt } A null onlineStoreUrl means the product is not published to the online store sales channel. Nothing in your frontend can fix that

Run the whole set once and you will usually know which half of the stack to open. The first four symptoms almost always resolve to the frontend; the last one never does.

Shopify GraphiQL app permissions: which scopes to toggle

Toggle the narrowest scope that covers the object you are querying, and expect permission errors to be the single most common failure. Search for "Shopify GraphQL app permissions" and the results tell the story: four of the eight organic listings on page one are Shopify Community threads, two of them specifically about missing permissions on a staff account. That is the real failure mode, not query syntax.

For reading products through the Storefront API, Shopify documents the required scope as unauthenticated_read_product_listings on the Product object itself. If a field comes back as null while the admin clearly shows a value, check the scope before you rewrite the query.

Two limits are worth knowing before you start generating tokens. Tokenless Storefront API access is capped at a query complexity of 1,000, and over-limit queries fail with MAX_COMPLEXITY_EXCEEDED rather than a truncated result. A shop can also hold a maximum of 100 active storefront access tokens, which agencies spinning up a token per client project do eventually hit.

One more trap: Storefront throttling does not return a 429. It returns HTTP 200 with extensions.code set to THROTTLED, so naive client code treats a throttle as a successful empty response. That is exactly how a Framer page ends up rendering a blank grid with no error in the console.

Pin the API version before you compare anything

Select the same API version in GraphiQL that your plugin requests, or you are comparing two different APIs. Shopify ships a new version every three months and supports each stable version for a minimum of 12 months, with at least nine months of overlap between consecutive versions. 2026-10 is the current stable version and is available for production use until at least October 1, 2027.

Stable versions are "guaranteed not to change for its supported lifetime." — Shopify, API versioning documentation

That guarantee is why version mismatch is such a quiet bug. Request a retired version and Shopify falls forward to the oldest accessible stable version instead of erroring, then tells you so in the X-Shopify-API-Version response header. Your query works, returns plausible data, and silently came from a different schema than the one you wrote against. Check that header on your own storefront requests too — we covered the specific field moves in the 2026-07 Storefront API changes.

If the version matches and the data is right in GraphiQL, you have narrowed the problem to the layer between Shopify and the page: the sync, the cache, or the binding. That is the layer FramerLink owns, and it is also why inventory drift is worth testing this way before a launch rather than after one.

Make it a habit, not a panic move

Keep three or four of these queries in a scratch file and run them before every storefront handoff. Ten minutes in GraphiQL on a staging store is cheaper than a client emailing you a screenshot of a wrong price on a Friday afternoon, and it means that when something does break, your first message is "Shopify is returning the right data" instead of a guess.

Frequently asked questions

What is API on Shopify?

A Shopify API is an endpoint that returns your store's data as structured JSON instead of a rendered page. Shopify ships several: the Admin API for managing a store, and the Storefront API for reading products, prices and inventory from an external frontend like a Framer site.

Is there a REST API for Shopify?

Yes, but GraphQL is now the primary interface for new work, and the GraphiQL explorer only speaks GraphQL. For a headless Framer storefront you want the GraphQL Storefront API, because that is the endpoint your plugin or custom code is already calling on every page load.

Is the Shopify API free?

Access to the Admin and Storefront APIs is included with a Shopify plan at no extra charge, and the GraphiQL app costs nothing to install. You pay in rate limits rather than dollars: query complexity and throttling rules cap how much you can request per request.

Sources