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 1 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
firstcost more - Expect throttling responses; back off and retry
- Check
extensions.cost.throttleStatuson 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:
errorsarray at the top level: GraphQL-level errors (malformed query, missing required argument, unauthorized field access). Always check.- Rate-limit extensions:
extensions.cost.throttleStatusshows 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.
What ships with production GraphQL code
A well-built Shopify GraphQL client has:
- Explicit fragment-based query shape
- Cursor pagination on every connection query
userErrorsselection on every mutation- Top-level
errorsarray checked on every response - Rate-limit aware retry logic respecting the cost status
- Correlation IDs logged for every call
- Metrics on call volume, call cost, and throttle frequency
Each of these catches a specific failure mode that silent-first-time integrations typically miss.
