Shopify GraphQL: query and mutation structure patterns that scale

Shopify's Admin API and Storefront API run on GraphQL. Querying a product is conceptually simple - specify fields, get values. The production patterns - connections for large lists, cursor-based pagination, handling userErrors from mutations, batching - are where most integrations slow down or break silently.

Two specific patterns show up repeatedly in real-world Shopify integration code.

Querying a product with variants

The Admin API Product type has scalar fields (handle, title) and connection fields (variants, metafields, images). Connections use the Relay-style pagination spec.

Wrong way (returns only first variant by default, silent truncation):

{
  product(id: "gid://shopify/Product/123") {
    title
    variants {
      id
      title
    }
  }
}

The Admin API rejects this because connections require an explicit first: argument.

Right way:

{
  product(id: "gid://shopify/Product/123") {
    handle
    title
    variants(first: 250) {
      edges {
        node {
          id
          title
          price
          sku
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

For products with more than 250 variants, follow endCursor with an after: argument on the next call. The pagination pattern holds across every GraphQL connection in the Shopify API.

Creating a resource with a mutation

Mutations follow a consistent shape: an input object, a return payload, and userErrors for business-logic validation failures.

Example: catalogCreate

mutation CreateCatalog($input: CatalogCreateInput!) {
  catalogCreate(input: $input) {
    catalog {
      id
      title
      status
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables:

{
  "input": {
    "title": "B2B Wholesale Catalog",
    "status": "ACTIVE",
    "context": { "companyLocationIds": ["gid://shopify/CompanyLocation/456"] }
  }
}

The critical piece: always select userErrors. HTTP 200 doesn't mean the mutation succeeded - the mutation can return 200 with userErrors populated explaining why the input was invalid (missing required field, invalid relationship reference, conflicting state).

Skipping userErrors is the most common bug in first-time Shopify GraphQL integrations. The mutation "succeeds" at the HTTP layer, the integration thinks the operation worked, and downstream logic runs on a resource that was never actually created.

Choosing between query structures

Shopify documents often show multiple valid query structures for the same data. A rule of thumb for picking:

Prefer explicit field lists over wildcards. GraphQL lets you ask for exactly the fields you need. Asking for more increases the query's cost (Shopify charges GraphQL calls by calculated cost, not per-call flat). Minimal field sets keep rate limits comfortable.

Prefer id + business key over full object references. When you're going to follow up with a mutation, a query returning the id is usually enough to perform the write. Fetching the entire related object in the first query is wasteful if you only need one field.

Use fragments for repeated shapes. When multiple queries share the same sub-structure (e.g., a Money shape or a ProductSummary shape), define a fragment once and reuse. Keeps query bodies clean and easier to maintain.

Pagination patterns

The Relay-style cursor pagination applies to every Shopify connection. Two usage patterns:

Read-all (catalog export):

after = None
all_products = []
while True:
    result = query(PRODUCTS_QUERY, {"first": 250, "after": after})
    products = result["data"]["products"]
    all_products.extend([edge["node"] for edge in products["edges"]])
    if not products["pageInfo"]["hasNextPage"]:
        break
    after = products["pageInfo"]["endCursor"]

Read-with-limit (on-demand display): Skip pagination; fetch the first: 50 or whatever the UI needs. Store cursors in session if the user can paginate further.

For catalog exports, the bulk operations API is faster still - it's designed for this volume. Use GraphQL pagination when you need dynamic query shape; bulk operations when you need every record.

Rate limiting and query costs

Shopify rate-limits GraphQL calls by a cost score. Each field has a calculated cost; your app has a cost budget per second. Exceed the budget and you get throttled (HTTP 200 with a rate-limit extension, not HTTP 429 like REST).

Implications:

Deep nested queries cost more
Connection queries with large first cost more
Expect throttling responses; back off and retry
Check extensions.cost.throttleStatus on every response to see your headroom

For high-volume integrations, batch work, spread it across time, use the Bulk Operations API for large exports.

Error handling beyond userErrors

Beyond userErrors on mutations, watch for:

errors array at the top level: GraphQL-level errors (malformed query, missing required argument, unauthorized field access). Always check.
Rate-limit extensions: extensions.cost.throttleStatus shows remaining budget. When exhausted, responses fail until budget regenerates.
Network-level failures: retry with exponential backoff on 5xx, timeouts, connection errors.

A production client handles all three layers.

Storefront vs Admin API

Similar shape, different surface:

Admin API: authenticated with app credentials, full merchant context, can mutate all resources
Storefront API: authenticated with storefront access token, customer-facing data only, limited mutation surface (cart, checkout)

For headless frontends, Storefront API is the primary data source. For admin integrations (ERP sync, bulk updates, analytics pulls), Admin API.