Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 55 ยท Admin GraphQL API

GraphQL for Shopify Developers

Learn the GraphQL you need for Shopify apps: queries, mutations, variables, fragments, aliases, introspection and gid:// global IDs, with a runnable query builder.

Shopify's Admin API is GraphQL first: new features arrive there, and it is the API your app template uses by default. GraphQL is not hard, but it works differently from a REST API where each URL returns a fixed JSON shape. Here you send one request to one URL and describe exactly the fields you want; the response mirrors your question.

This lesson teaches the parts of GraphQL you will use every day in a Shopify app: queries, mutations, variables, fragments, aliases, introspection and Shopify's global IDs. The real requests need a shop and a token, so they are shown read-only. You can still practice everything with a small query builder written in plain JavaScript that runs on this page. Examples target the Admin API version 2026-07, used as a stand-in for "a recent stable version" (see API Versioning and Deprecations).

One endpoint, one POST

Every Admin GraphQL request is a POST to the same URL for your shop and version, with the access token in a header (Token Exchange and Access Tokens):

HTTP
POST https://example-store.myshopify.com/admin/api/2026-07/graphql.json
Content-Type: application/json
X-Shopify-Access-Token: <access token>

{
  "query": "query { shop { name } }"
}

The body is JSON with a query string and, optionally, variables and operationName. The response is JSON with a data object shaped like your query, and sometimes an errors array. In an app you rarely write this by hand: admin.graphql(...) from the template builds the request for you.

flowchart LR
  Q["Query text<br/>+ variables"] --> S["Shopify GraphQL server"]
  S --> D["data: same shape as the query"]
  S --> E["errors: what went wrong (optional)"]

The request describes the shape; the response comes back in that shape.

Queries: asking for exactly what you need

A query reads data. You list fields, and for objects you list the fields inside them:

GRAPHQL
query ShopBasics {
  shop {
    name
    myshopifyDomain
    currencyCode
  }
}

The response has the same structure, containing only those three fields:

JSON
{
  "data": {
    "shop": {
      "name": "Example Store",
      "myshopifyDomain": "example-store.myshopify.com",
      "currencyCode": "USD"
    }
  }
}

If you want less data, ask for fewer fields. There is no "give me everything" shortcut, which is what keeps responses small and queries cheap (you will see why cost matters in Rate Limits and Query Cost).

Lists in Shopify use connections: a field such as products(first: 5) returns a page of items, and you choose whether to read them through nodes or edges { node }. Pagination with Cursors covers this properly; here we just use nodes.

GRAPHQL
query FirstProducts {
  products(first: 3) {
    nodes {
      id
      title
      status
    }
  }
}

Global IDs

Every Shopify object has a global ID, a string that includes the object's type:

Text
gid://shopify/Product/9876543210
gid://shopify/ProductVariant/12345
gid://shopify/Order/555

The format is gid://shopify/<Type>/<number>. Three practical rules follow:

  • Pass the whole string. A bare number such as 9876543210 is not accepted where an ID is expected.
  • Store the whole string in your database, or store the numeric part together with the type. Mixing the two causes bugs.
  • The type is part of the identity. Product 1 and variant 1 are different objects; the gid makes that explicit and lets you route by type, for example when reading bulk operation results.

The numeric part is what you see in admin URLs (/products/9876543210) and in REST payloads and webhook bodies; webhook payloads often carry an admin_graphql_api_id field with the full gid.

Variables: never build queries with string concatenation

Hard-coding values into the query text works, but it is fragile and unsafe when the values come from users. GraphQL separates the query from its variables:

GRAPHQL
query ProductById($id: ID!) {
  product(id: $id) {
    title
    handle
  }
}
JSON
{ "id": "gid://shopify/Product/9876543210" }

$id: ID! declares a variable called id of type ID; the exclamation mark means it is required. Send the query and the variables as two separate JSON fields. This avoids injection problems (user input is never part of the query text), and it lets Shopify cache and analyze the query shape.

In the template, it looks like this (read-only):

TypeScript
const response = await admin.graphql(
  `#graphql
  query ProductById($id: ID!) {
    product(id: $id) { title handle }
  }`,
  { variables: { id: "gid://shopify/Product/9876543210" } },
);
const { data } = await response.json();

The #graphql comment tells editor tooling that the string is GraphQL; it is not required by the API.

Mutations: changing data

A mutation writes data. It looks like a query but starts with mutation, takes an input argument and returns the object it changed plus any userErrors:

GRAPHQL
mutation RenameProduct($input: ProductInput!) {
  productUpdate(product: $input) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}
JSON
{ "input": { "id": "gid://shopify/Product/9876543210", "title": "Canvas Tote Bag" } }

Mutation names, argument names and input types do change between API versions, so always check the reference for the version you target. Mutations and userErrors explains the userErrors pattern in depth, which is the most important habit to learn here: a mutation can "succeed" at the HTTP level and still have refused your change.

Fragments and aliases

Two features keep queries tidy.

A fragment names a reusable set of fields:

GRAPHQL
fragment ProductBasics on Product {
  id
  title
  handle
}

query Two {
  newest: products(first: 1, sortKey: CREATED_AT, reverse: true) {
    nodes { ...ProductBasics }
  }
  oldest: products(first: 1, sortKey: CREATED_AT) {
    nodes { ...ProductBasics }
  }
}

An alias (newest:, oldest:) renames a field in the response. You need aliases when you call the same field twice with different arguments, as above; without them the two results would collide under the name products.

Introspection: the API describes itself

A GraphQL server can answer questions about its own schema. For example:

GRAPHQL
query {
  __type(name: "Product") {
    fields { name }
  }
}

Tools such as GraphiQL (available through the CLI's local development tooling) use introspection to power autocompletion. When you wonder "what fields does Product have in this version?", introspection and the version-specific reference are always more reliable than memory or old blog posts.

A query builder you can run

Real requests cannot run here, but the text of a query is just a string, and building it safely is something you can practice. This stand-in builds a query from a list of fields, supports nested fields, arguments and aliases, and prints the request body you would POST.

Node.js Build a GraphQL query from data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that the product id never appears inside the query text. It travels in variables, exactly as in a real request.

Checking a global ID

Since a malformed ID is a common source of errors, a tiny parser is worth having. This second stand-in splits a gid, checks the type you expect, and rejects bare numbers.

Node.js Parse and validate global IDs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last line shows that some IDs can carry a query string (for example on certain job or session-style objects). Treat the gid as an opaque string you pass back unchanged; only parse it when you have to.

Reading errors

GraphQL responses can contain two different kinds of failures, and mixing them up leads to subtle bugs:

  • A top-level errors array means the request itself was wrong or failed: a syntax error, an unknown field, missing access scope, or throttling.
  • userErrors inside a mutation's payload means the request was valid but Shopify refused the change, for example a duplicate handle.

A response can also have data and errors at the same time if some fields resolved and others did not. Check for both. We build a reusable wrapper in Mutations and userErrors.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How many URLs does the Admin GraphQL API use for a given shop and version?

    All operations are POSTed to the same graphql.json URL for your shop and version; the query text selects the data.
  2. 2. Why should values from users be sent as variables instead of inserted into the query text?

    Keeping user input out of the query string prevents injection mistakes and keeps the query text constant.
  3. 3. Which value is a valid Shopify global ID for product 42?

    Global IDs have the form gid://shopify/<Type>/<number>, and you pass the whole string.
  4. 4. You need the newest and the oldest product in one request. What lets you call products twice?

    Aliases rename each call in the response (newest and oldest), so the two results do not collide.
  5. 5. A mutation returns HTTP 200 with data and a non-empty userErrors list. What happened?

    userErrors report business-rule failures inside a successful HTTP response. Always check them after a mutation.

Summary

  • Admin GraphQL is one POST endpoint per shop and API version; you describe the fields you want and receive that shape back.
  • Queries read, mutations write; both can take typed variables, which keep user input out of the query text.
  • Global IDs look like gid://shopify/Type/number; pass and store the whole string.
  • Fragments reuse field sets, aliases rename results so a field can be called twice, and introspection lets the API describe itself.
  • Distinguish top-level errors from mutation userErrors, and check both.

Next: API Versioning and Deprecations shows how to pick and upgrade the version in that URL.