What is the Shopify GraphQL Admin API?

If you've heard "Shopify has an API" but weren't sure what that means in practice, here's the short version: the GraphQL Admin API is the programmatic door into your store. It lets you—or software you've authorized—read and change almost anything in your Shopify store's data: product catalogs, customer records, orders, inventory levels, fulfillment details, and dozens of other resource types. Understanding this API is the foundation for building Shopify apps, writing automation scripts, or connecting your store to external systems.

How it works

GraphQL—short for Graph Query Language—is a way of asking for exactly the data you want, in the shape you want it. Unlike a REST API where each endpoint returns a fixed set of fields, GraphQL lets you write a query that says exactly which fields to return. This means you never get more data than you asked for, and you can retrieve data from multiple resource types in a single request.

There are two fundamental operation types. A query reads data—it doesn't change anything. A mutation creates, updates, or deletes data. For example, fetching a list of products is a query; adding a tag to a product is a mutation. Here's what a basic query looks like:

# Query: fetch the first 5 products with their titles and price ranges
query {
  products(first: 5) {
    nodes {
      id
      title
      priceRangeV2 {
        minVariantPrice {
          amount
          currencyCode
        }
      }
    }
  }
}

Shopify provides a built-in tool called GraphiQL (pronounced "graphical") that lets you explore the API interactively without writing any code. From your Shopify admin, navigate to /admin/api/2024-10/graphql.json using the Shopify GraphiQL App. You can write queries, see auto-complete suggestions, and inspect the full API schema from within the browser.

GraphQL Admin API vs REST Admin API

Shopify has had a REST Admin API since 2007, long before GraphQL was invented. If you've looked at older Shopify tutorials or integrations, they likely use REST—endpoints like GET /admin/api/2024-10/products.json. Both APIs can access the same underlying data, but they differ significantly in design and long-term direction.

GraphQL is now the preferred API for all new Shopify development. New capabilities—like the Subscriptions API, Markets API, and Shopify Functions—are only available via GraphQL. REST is officially in "maintenance mode": Shopify still supports it for existing integrations, but no new features are being added to the REST API. If you're starting a new project, use GraphQL.

The practical differences:

• Efficiency: GraphQL returns only the fields you request. REST returns fixed payloads that often include fields you don't need, wasting bandwidth.
• Batching: A single GraphQL query can join across resource types (e.g., "give me 10 orders with their customer names and fulfillment details"). In REST, that would require multiple serial API calls.
• Strong typing: GraphQL has a formal schema. Your editor can auto-complete field names and catch typos before your code runs. REST's implicit field structure has no built-in type enforcement.
• Learning curve: REST is simpler to start with—you can call it with curl or a browser. GraphQL requires learning the query syntax. But the learning curve is small and pays back quickly.

Rate limiting (cost-based throttling)

Shopify's GraphQL Admin API uses a cost-based throttling model, which is very different from REST's simple requests-per-minute limit. Every GraphQL query has a "cost"—a number that reflects how many resources Shopify had to calculate to respond. Simple queries cost less; queries that join many resource types or request large page sizes cost more. You have a bucket of 2,000 points (cost units) that refills at 100 points per second. If you make a query that costs 500 points, your bucket drops to 1,500. A second later, it refills to 1,600.

Every GraphQL response includes a extensions.cost field in the JSON that tells you the actual cost of the query you just ran, the current bucket state (throttle status), and what the maximum cost available is. Watch this field during development—if your queries are expensive, you'll hit the throttle sooner than you expect.

{
  "data": { ... },
  "extensions": {
    "cost": {
      "requestedQueryCost": 22,
      "actualQueryCost": 22,
      "throttleStatus": {
        "maximumAvailable": 2000,
        "currentlyAvailable": 1978,
        "restoreRate": 100
      }
    }
  }
}

To stay under the limit: request only the fields and page sizes you actually need (requesting first: 250 costs more than first: 10); use the Bulk Operations API (described below) for large data exports; add retry logic with exponential backoff when you receive a THROTTLED error code.

Common patterns

Pagination with cursors. The GraphQL API uses cursor-based pagination. When you request a list of resources, you get back a pageInfo object with hasNextPage and endCursor. To get the next page, pass after: endCursor in your next query.

# First page
query {
  products(first: 10) {
    nodes { id title }
    pageInfo { hasNextPage endCursor }
  }
}

# Second page (pass the endCursor from the previous response)
query {
  products(first: 10, after: "eyJsYXN0X2lkIjo...") {
    nodes { id title }
    pageInfo { hasNextPage endCursor }
  }
}

Bulk Operations API. When you need to export all products, orders, or customers from a large store (thousands to millions of records), cursor pagination is too slow and too expensive. The Bulk Operations API lets you start a background job that exports data to a JSONL file you can download. You fire the bulkOperationRunQuery mutation, poll for completion, then download the result file from a CDN URL. It's the right tool for any data export that touches more than a few hundred records.

Fragments. As your queries grow, you'll find yourself repeating the same field selections. GraphQL fragments let you define a reusable set of fields and spread them into multiple queries with ...FragmentName syntax. This is especially useful in app code where you want to share product field selections between a list page query and a detail page query.

Making your first API call

You can make a GraphQL Admin API call with any HTTP client that can send POST requests with custom headers. All you need is a valid access token (from OAuth or from a custom app) and the store's domain. The endpoint URL follows a consistent pattern across all Shopify stores and API versions, making it straightforward to construct programmatically.

# Using curl — replace YOUR_STORE and YOUR_ACCESS_TOKEN
curl -X POST \
  https://YOUR_STORE.myshopify.com/admin/api/2024-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: YOUR_ACCESS_TOKEN' \
  -d '{
    "query": "{ shop { name primaryDomain { url } } }"
  }'

A successful response returns a JSON object with a data key containing your requested fields. If there are errors in your query (wrong field names, missing required arguments), they come back in an errors array at the top level—not as an HTTP error code. This is a key difference from REST APIs: the HTTP status code from a GraphQL endpoint is almost always 200, even when the query had problems.

Variables and mutations in practice

Hard-coding values directly into a GraphQL query string creates two problems: you can't reuse the query with different inputs, and you open yourself to injection attacks if you're interpolating user input. GraphQL variables solve both issues. You declare named variables in the operation signature (prefixed with $), use them in the query body, and pass actual values in a separate variables JSON object in the request.

# Mutation with variables (don't hardcode IDs in the query string)
mutation UpdateProductTitle($id: ID!, $title: String!) {
  productUpdate(input: { id: $id, title: $title }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

# variables object (sent alongside the query in the JSON request body):
# {
#   "id": "gid://shopify/Product/123456",
#   "title": "New Product Title"
# }

Notice the id format: Shopify uses Global IDs (GIDs) like gid://shopify/Product/123456 rather than plain numeric IDs in the GraphQL API. GIDs uniquely identify a resource across all of Shopify's infrastructure regardless of type. When building queries, always use GIDs—if you're working with numeric IDs from the REST API, you can construct the GID manually by prepending the resource type prefix.

Introspection and staying up to date with API versions

GraphQL's schema is self-documenting through a feature called introspection. You can query the schema itself to discover all available types, fields, and mutations without reading external documentation. Tools like GraphiQL use introspection under the hood to power their auto-complete suggestions. In a Node.js project, running graphql-codegen against the Shopify API schema generates TypeScript types automatically, giving you compile-time checking for every query and mutation you write.

Shopify deprecates older API versions and removes them after 12 months. Deprecated fields within a version are flagged in the schema (they show as deprecated in GraphiQL with a strikethrough). Shopify announces upcoming deprecations well in advance in their developer changelog at shopify.dev/changelog. Subscribe to that changelog and review it regularly—missing a deprecation notice has broken more than a few production apps on the sunset date.