Shopify Admin GraphQL

GraphQL in one minute

A normal REST API gives you fixed URLs that return fixed data. GraphQL gives you one URL where you describe exactly what you want, and get back exactly that — no more.

{
  product(id: "...") {
    title
    handle
  }
}

{
  "data": {
    "product": {
      "title": "T-Shirt",
      "handle": "t-shirt"
    }
  }
}

The shape of the answer matches the shape of the question. Ask for three fields, get three fields.

Making a call

authenticate.admin hands you an admin client. It returns a normal HTTP response, so you call .json() on it.

export const loader = async ({ request }) => {
  const { admin } = await authenticate.admin(request);

  const response = await admin.graphql(
    `#graphql
      query GetProduct($id: ID!) {
        product(id: $id) {
          id
          title
          status
        }
      }`,
    { variables: { id: "gid://shopify/Product/123" } },
  );

  const json = await response.json();
  const product = json.data.product;

  return { product };
};

Three details worth noticing:

• #graphql at the start is a comment that turns on syntax highlighting and validation in your editor. Always include it.
• $id: ID! declares a variable. The ! means required.
• Your data is always nested under json.data.

// WRONG — breaks on quotes, and is unsafe
admin.graphql(`{ product(id: "` + userInput + `") { title } }`);

// RIGHT — pass it as a variable
admin.graphql(query, { variables: { id: userInput } });

GIDs: Shopify's ids

Shopify's GraphQL API does not use plain numbers. Everything has a global id:

gid://shopify/Product/8379080704066
gid://shopify/ProductVariant/45123456789
gid://shopify/Order/5544332211

The number at the end is the id you see in admin URLs. You will convert between the two constantly:

// number → GID
const gid = `gid://shopify/Product/${id}`;

// GID → number
const id = gid.split("/").pop();

Mutations: changing data

Same shape, but you also ask for userErrors — and this is the most important thing in this note.

const response = await admin.graphql(
  `#graphql
    mutation UpdateProduct($product: ProductUpdateInput!) {
      productUpdate(product: $product) {
        product { id title }
        userErrors { field message }
      }
    }`,
  { variables: { product: { id: productGid, title: "New title" } } },
);

const json = await response.json();
const errors = json.data?.productUpdate?.userErrors ?? [];

if (errors.length > 0) {
  console.error(errors);
  return { error: errors[0].message };
}

Pagination: the "where are the rest?" problem

Lists in GraphQL are connections, and they never return everything. You must say how many you want, and the maximum is 250.

query {
  products(first: 50) {
    nodes { id title }
    pageInfo { hasNextPage endCursor }
  }
}

nodes is your list. pageInfo tells you whether more exist and gives you a cursor — a bookmark marking where you stopped.

The loop you will copy repeatedly

async function getAllProducts(admin) {
  const all = [];
  let cursor = null;

  do {
    const response = await admin.graphql(
      `#graphql
        query GetProducts($cursor: String) {
          products(first: 100, after: $cursor) {
            nodes { id title }
            pageInfo { hasNextPage endCursor }
          }
        }`,
      { variables: { cursor } },
    );

    const json = await response.json();
    const page = json.data.products;

    all.push(...page.nodes);
    cursor = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
  } while (cursor);

  return all;
}

Nested lists paginate too. A product's variants are their own connection — a product with 300 variants will not return them all in one go, which is exactly how "only some colours show up" bugs happen.

Rate limits

Shopify does not count your requests. It counts how expensive they are.

Think of a bucket of points that refills steadily. Every call costs points based on how much data it asks for. Ask for too much too fast and the bucket empties.

Two practical defences:

• Ask for less. Request only the fields you use. Deeply nested queries cost far more than flat ones.
• Retry with a wait. For loops and background jobs, catch the throttle and try again after a pause.

async function withRetry(fn, tries = 5) {
  for (let i = 0; ; i++) {
    try {
      return await fn();
    } catch (err) {
      const throttled = JSON.stringify(err).includes("THROTTLED");
      if (!throttled || i >= tries) throw err;
      await new Promise((r) => setTimeout(r, 1000 * (i + 1)));  // back off
    }
  }
}

Also: process things one at a time in loops. Firing 200 requests at once with Promise.all is the fastest way to get throttled.

Metafields: storing your data on Shopify

A metafield is extra data attached to a product, order or customer — your own field on Shopify's record. Useful when the storefront needs to read it, because your database is not reachable from a theme.

Each one has a namespace (your grouping), a key (the name), a type, and a value.

Reading

query GetMetafield($id: ID!) {
  product(id: $id) {
    metafield(namespace: "custom", key: "my_config") { value }
  }
}

Writing

mutation SetMetafield($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields { id }
    userErrors { field message }
  }
}

variables: {
  metafields: [{
    ownerId:   productGid,
    namespace: "custom",
    key:       "my_config",
    type:      "json",
    value:     JSON.stringify({ color: "blue" }),   // always a string
  }],
}

API versions

Shopify releases a new API version every three months, named by date — 2026-01. Your app pins one:

apiVersion: ApiVersion.October25,   // in shopify.server.js

Pinning means Shopify will not change under you. Versions are supported for about a year, so plan to move up roughly annually.

Write queries the easy way

Do not write GraphQL blind in your editor. Run:

shopify app graphiql

It opens a browser tool connected to your dev store with autocomplete, inline documentation, and instant results. Build the query there, confirm the response shape, then paste it into your code.

Common errors

console.log(JSON.stringify(json, null, 2));

Checklist for every API call

• Values passed as variables, never concatenated into the string.
• Only the fields you actually use are requested.
• Mutations ask for userErrors — and the code checks it.
• Any list that could exceed one page is paginated with a cursor loop.
• Loops run sequentially, with a retry on throttling.
• Tested in GraphiQL before being pasted into code.

Cheat sheet

# call
const res  = await admin.graphql(query, { variables });
const json = await res.json();
json.data.thing

# ids
gid://shopify/Product/123        always store the full GID

# mutation — non-negotiable
userErrors { field message }     ask for it, then CHECK it

# pagination
first: 100, after: $cursor
pageInfo { hasNextPage endCursor }   loop until hasNextPage is false

# silent failures (all return HTTP 200)
userErrors populated  → your write did nothing
THROTTLED             → rate limited, not an error code
only 50 results       → you forgot to paginate

# tool
shopify app graphiql             build and test queries here first