What we do
Tools
Industries
Department
How we workLet's talk →
Home/Shopify/Shopify API Documentation, Mapped for Builders
Shopify API

Shopify API Documentation, Mapped: Which API, Which Token, Which Limits

Shopify's developer docs at shopify.dev cover a dozen APIs. Most integrations only need three of them: the GraphQL Admin API for store data, webhooks to hear about changes, and an access token from an app. This page is the map: which section answers which job, how to make the first call, and what the reference pages mention once and then never again.

Short version

Reading or writing orders, products, customers or stock? Use the GraphQL Admin API. The REST Admin API has been legacy since October 2024, and new public apps have had to use GraphQL only since April 2025.

Building your own storefront or mobile app? Use the Storefront API. It's GraphQL too, with its own tokens.

Need to know when something changes? Subscribe to webhooks instead of polling, and verify every delivery.

Your first GraphQL Admin API call, from nothing

For an integration that runs on your own store. The same steps apply to a client's store, except step four.

  1. 1

    Create the app in the Dev Dashboard

    New custom apps start in Shopify's Dev Dashboard now, not as legacy custom apps inside the store admin. You'll get a client ID and client secret there.

  2. 2

    Choose access scopes on the app version

    Ask for what the job needs, such as read_orders and write_inventory, and nothing more. Scopes are approved on the store at install, so adding one later means another approval.

  3. 3

    Install it on the store

    Use a dev store from the Dev Dashboard for testing, then the real store. Until the app is installed, no token request will work.

  4. 4

    Exchange credentials for a token

    For stores in your organization, the client credentials grant swaps the client ID and secret for a token that lasts 24 hours, so request a fresh one on a schedule. For anyone else's store, use the OAuth authorization code flow.

    Watch for: a shop_not_permitted error means the store isn't in the same organization as the app, even if you own it.

  5. 5

    Make the call and read the cost

    POST to https://{store}.myshopify.com/admin/api/2026-10/graphql.json with the token in the X-Shopify-Access-Token header. Every response carries the query's cost under extensions. Log it from day one, because that number decides how fast your sync can go.

Which part of the Shopify docs answers your job

Everything below lives on shopify.dev. The right-hand column is what people usually learn the hard way.

You need to Read this section What catches people
Read and write store data: orders, products, customers, inventory, fulfillments, metafields GraphQL Admin API reference, plus its rate limits page. Limits are a budget of query cost points per second, per app and store, not a request count. Standard plans get 100 points a second, Plus gets 1000.
Keep an older integration running REST Admin API reference. It still answers, but it's legacy and some newer features only exist in GraphQL. Plan the move before a feature you need forces it.
Power a headless storefront, app or kiosk Storefront API. It's a different API with different tokens. It reads catalog data and manages carts and checkout, it doesn't do back-office writes.
React to orders, refunds and stock changes as they happen Webhooks: topics, delivery structure, verify deliveries, troubleshoot. Your endpoint has five seconds to answer, and Shopify removes a subscription after repeated failures. Pub/Sub or EventBridge delivery takes that pressure off at volume.
Export or load a whole catalog or order history Bulk operations in the GraphQL Admin API. Paging through a large store with normal queries burns your cost budget. A bulk query runs on Shopify's side and hands you a file.
Get an access token Apps > authentication and authorization, and the Dev Dashboard. The client credentials grant only works for stores in your own organization. A client's store means an install with OAuth.
Pin your code to a stable contract API versioning. A new version ships each quarter and lasts at least a year. Call a retired version, or none, and Shopify quietly serves the oldest supported one instead.

What the reference pages say once and you need daily

A sync that passed testing throttles in production

How you'll know: THROTTLED errors start on the first big sales day, while a dev store with ten orders never showed one.

Fix: Ask only for fields you use, keep page sizes sensible, and pace requests off the cost each response reports. Move full exports to bulk operations.

Webhooks that do the work before answering

How you'll know: Delivery logs show response times creeping toward five seconds, then failures, then a topic that stops arriving.

Fix: Verify the HMAC, store the payload, return 200 at once, and process it from a queue. If a subscription was removed, recreate it and backfill the gap from the API.

HMAC checks that fail on valid deliveries

How you'll know: Every signature mismatches, even from Shopify.

Fix: The signature is computed over the raw request body. A JSON body parser that runs first changes the bytes. Verify before parsing.

The same order processed twice

How you'll know: Duplicate invoices or double stock deductions after a network blip.

Fix: Keep a record of each X-Shopify-Webhook-Id and skip repeats, or make every write idempotent so a second delivery changes nothing.

Trusting webhooks to be complete

How you'll know: Most orders reach the ERP and a few never do.

Fix: Shopify says deliveries can arrive late, even by a day. Add a scheduled query that compares recent orders against what your system received.

Where the Shopify documentation stops

The docs tell you what each query, mutation and webhook topic does. They don't design the sync for you: which system owns the stock count, what happens when your ERP and Shopify disagree about an order's state, how a partial refund should land in the books. That's the part that takes the time, and the part Shopify Flow can't cover once the logic needs data from outside the store.

There's also a small set of work with no API at all: some admin-only settings, certain reports, and the configuration screens inside third-party apps that never exposed an endpoint. When a workflow depends on one of those, n-frames automates the admin screen itself, alongside the API work, so the process doesn't wait on an endpoint that may never ship. The same goes for checkout customization and inventory jobs that sit half in and half out of the API.

Questions people ask

Where is the Shopify API documentation?

On shopify.dev, under the API reference for each API: the GraphQL Admin API, the legacy REST Admin API, the Storefront API, webhooks and the rest. The app-building guides, including authentication, rate limits and versioning, sit beside the references.

What's the difference between Shopify's Admin API and Storefront API?

The Admin API manages your store's back office from outside the Shopify admin: orders, products, customers, inventory. The Storefront API is for building your own front end, such as a headless storefront, mobile app or kiosk, that reads products and manages a cart without Shopify's theme engine. Back-office integrations use the Admin API, headless builds use the Storefront API, and some projects use both.

Is Shopify's REST API going away?

It hasn't been switched off, but Shopify made the REST Admin API legacy in October 2024, and since April 2025 new public apps must use the GraphQL Admin API only. Some newer features exist only in GraphQL. Anything new should start on GraphQL.

What is a Shopify webhook, and how do I use one?

It's Shopify sending a POST to an endpoint you control the moment something happens, such as orders/create or products/update, so you don't have to keep asking. You subscribe in your app's configuration or through the Admin API, verify the HMAC signature on each delivery, answer within five seconds, and process the payload afterwards.

Where do I find my Shopify API key and access token?

In the Dev Dashboard, on the app you created: that's where the client ID and secret live. The access token itself comes from a token request, either the client credentials grant for stores in your organization or OAuth for other stores, rather than being shown in the store admin.

Can I get Shopify data that isn't in the Admin API?

Sometimes not directly. A few admin settings, some reports and many third-party app configuration screens were never given an API. Then the practical route is automating the admin interface itself, which n-frames builds when a client's workflow depends on one of them.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.