The Shopify API
Explained in plain English.

1. What the Shopify API is

The Shopify API is the set of programmatic interfaces that let software read and write a store's data — products, orders, customers, inventory, discounts, fulfillment, and much more. When a Shopify app shows a merchant their subscription analytics, or awards loyalty points when an order is placed, it's doing it through the Shopify API.

An app talks to the API over HTTPS, authenticated with an access token tied to a specific merchant's store. The API enforces what the app can do based on the permissions (scopes) the merchant granted at install. Everything an app does to a store — every read and every change — flows through these APIs.

Shopify doesn't expose a single API but a family of them, each suited to a different job. The one most apps spend their time in is the Admin GraphQL API, which is what this guide focuses on, while covering the others you'll encounter.

2. The Shopify API surfaces

Shopify offers several distinct APIs. Knowing which is which prevents a lot of confusion:

For building a typical Shopify app — a loyalty program, a subscription tool, a B2B portal — you live almost entirely in the Admin GraphQL API. The Storefront API matters if you're building headless commerce; the Functions API matters only if you need custom checkout logic. This guide centers on the Admin API since that's where app development happens.

3. GraphQL vs REST — which to use

Historically Shopify offered a REST Admin API. Today it offers both REST and GraphQL, but the direction is unambiguous: GraphQL is the present and future; REST is legacy.

Why GraphQL won

With GraphQL, you ask for exactly the fields you need in a single request, and you can fetch related data (an order plus its line items plus the customer) in one round trip. With REST, you'd make multiple requests and over-fetch data you don't need. GraphQL is more efficient, more flexible, and gets Shopify's newest features first.

The practical reality in 2026

Shopify has been actively deprecating REST endpoints and moving functionality to GraphQL-only. Some newer capabilities are available only through GraphQL. Building a new app on REST in 2026 means building on a shrinking foundation. Every new Shopify app should use the Admin GraphQL API.

What a GraphQL call looks like

You send a query (to read) or a mutation (to write) to a single GraphQL endpoint, specifying the version. For example, a mutation like productCreate creates a product; a query selects the fields you want back. The structure is consistent: pick your operation, pass the input, select the return fields you need.

4. API versioning

Shopify uses date-based API versioning. Versions are named in the format YYYY-MM and released quarterly: January, April, July, and October. As of mid-2026, the current stable version is 2026-04 (released April 2026), with the next quarterly version following in July.

How version support works

Each API version is supported for a minimum of 12 months from its release. After that, it's deprecated and eventually stops working. This means an app built against a given version must be updated periodically to stay on a supported version — roughly an annual maintenance task. Changes between versions are documented so you know what to update.

Specifying the version

You include the version in your API request path (for GraphQL, the endpoint path includes the version) or in your API client configuration. Pinning to a specific version means Shopify won't change the API behavior underneath you mid-release — you opt into new versions deliberately.

5. Authentication

Shopify API access is authenticated per-merchant using OAuth and access tokens. Here's the flow:

The OAuth handshake

When a merchant installs your app, Shopify redirects through an OAuth flow. Your app verifies the request (including an HMAC signature — see the webhooks guide for how HMAC verification works), then exchanges a temporary authorization code for a permanent access token. This token is scoped to exactly the permissions the merchant approved.

Using the access token

On every Admin API request, your app sends the access token in the X-Shopify-Access-Token header. Shopify validates it and processes the request within the granted scopes. The token is specific to one store — if your app is installed on 200 stores, you store 200 tokens, one per store, and use the right one for each request.

Scopes — request only what you need

Scopes (like read_products, write_orders) define what your app can access. Request only the scopes your app genuinely uses. Over-requesting scopes raises App Store review scrutiny and increases your security responsibility. Each scope is access you must protect.

Session tokens for embedded apps

For embedded apps (those that load inside the Shopify admin), the frontend authenticates requests to your backend using short-lived session tokens issued by App Bridge, rather than long-lived cookies. The App Bridge guide covers this in detail.

6. Rate limits

Shopify limits how fast apps can call the API, to protect platform stability. The two APIs use different models:

GraphQL: calculated query cost

The Admin GraphQL API assigns each query a cost in points based on how much data it requests. You have a points budget that refills continuously (a leaky-bucket system). Efficient queries — requesting only the fields you need — cost fewer points, letting you do more within the limit. Heavy queries cost more and drain the budget faster. The response tells you your current cost and remaining budget.

REST: request-count bucket

The legacy REST Admin API uses a simpler request-count bucket: you can make a burst of requests up to a limit, and the bucket refills at a steady rate. Exceed it and you get a 429 (Too Many Requests) response.

Handling limits correctly

A well-built app respects rate limits by: batching work into efficient queries, reading the cost/remaining info Shopify returns, and backing off and retrying when it approaches or hits the limit. Apps that ignore rate limits get throttled and deliver a broken experience to merchants during high-volume periods. Proper rate-limit handling is one of the things that separates a production-grade app from a prototype.

7. Common API tasks

To make this concrete, here's what real apps do with the Admin API:

• Read store data: fetch products, orders, customers, inventory levels — queries that power dashboards and logic.
• Create and update records: mutations like productCreate, draftOrderCreate, or updating inventory and metafields.
• Manage discounts: create and apply discount codes (a loyalty app generates discount codes from point balances this way).
• Subscribe to events: register webhooks so your app is notified when orders are created, customers update, or the app is uninstalled.
• Bill merchants: create subscription charges via the Billing API (the Billing API guide covers this).
• Store custom data: use metafields to attach custom data to Shopify objects, or your own database for app-specific data.

Almost every app feature reduces to some combination of these: read data, react to events, write changes, and bill for the value delivered.

8. How AI builders handle the API for you

Working with the Shopify API directly means learning GraphQL, managing OAuth and tokens, choosing the right API version, handling rate limits, and keeping all of it updated as Shopify evolves. That's real work, and it's where many DIY and generic-AI app attempts break down.

A Shopify-specific AI builder like Shopivibe handles this layer for you. You describe what the app should do — "award a loyalty point for every dollar spent, redeemable for discount codes" — and the builder generates the correct GraphQL queries and mutations, the OAuth flow, the access-token handling, rate-limit-aware request logic, and pins to a current API version. Because the generation is grounded in Shopify's actual documentation (not a generic model's guess), the API calls match what Shopify currently expects.

You still own the code. If you want to add a custom GraphQL query or adjust how the app calls the API, the generated code is standard and editable. The difference is you start from a correct, working API integration instead of debugging OAuth and rate limits from scratch.

9. FAQ