Shopify GraphQL Cost Optimizer

Overview

Every Shopify GraphQL query has a calculated cost. The API uses a token bucket (1,000 points max, refills at 50/second for standard plans) and throttles once depleted. The key insight:

requestedQueryCost

actualQueryCost

Prerequisites

• Shopify app with GraphQL Admin API access

• @shopify/shopify-api

  package installed
• Understanding of GraphQL connections (edges/node pattern)

Instructions

Step 1: Read Cost Headers

Every GraphQL response includes cost data in

extensions.cost

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 252,
      "actualQueryCost": 12,
      "throttleStatus": {
        "maximumAvailable": 1000.0,
        "currentlyAvailable": 988.0,
        "restoreRate": 50.0
      }
    }
  }
}

Add the

X-GraphQL-Cost-Include-Fields: true

Step 2: Predict Query Cost

Cost rules for calculation:

• Single object field: 1 point (e.g.,

  shop { name }

  = 1)
• Connection:

  first

  or

  last

  param multiplied by child cost, plus 2 for the connection itself
• Nested connections: costs multiply

# Example: products(first: 10) { edges { node { title variants(first: 5) { edges { node { price } } } } } }
# Cost = 2 (products connection) + 10 * (1 (title) + 2 (variants connection) + 5 * 1 (price))
# = 2 + 10 * (1 + 2 + 5) = 2 + 80 = 82 requestedQueryCost

See references/cost-calculation-rules.md for the full calculation rules.

Step 3: Cost Reduction Techniques

Reduce

first

# BAD: 250 * nested cost = massive
products(first: 250) { ... }

# GOOD: paginate with smaller pages
products(first: 25, after: $cursor) { ... }

Select only needed fields — every field costs 1 point per connection node:

# BAD: 10 fields * 50 products = 500+ points
products(first: 50) { edges { node { id title description vendor tags status productType totalInventory createdAt updatedAt } } }

# GOOD: 3 fields * 50 products = ~152 points
products(first: 50) { edges { node { id title status } } }

Avoid deep nesting — flatten or split queries. See references/query-splitting.md for patterns.

Step 4: Use Bulk Operations for Large Data Sets

When you need 250+ items, switch to

bulkOperationRunQuery

first

last

See references/bulk-operations.md for the complete

bulkOperationRunQuery

Output

• Query cost visible in every response via

  extensions.cost

• Queries optimized below 200 points each
• Bulk operations configured for large data exports
• Per-field cost breakdown available for debugging

Error Handling

THROTTLED

restoreRate

MAX_COST_EXCEEDED

first

QUERY_TOO_COMPLEX

BULK_OPERATION_FAILED

errorCode

BULK_OPERATION_ALREADY_RUNNING

Examples

Calculating Cost for a Nested Product Query

Predict the cost of a query that fetches products with variants and metafields before running it, to avoid unexpected THROTTLED errors.

See Cost Calculation Rules for the full calculation formula and worked examples.

Splitting an Expensive Query

A single query exceeds 1,000 points due to deep nesting. Break it into multiple cheaper queries that stay well under the limit.

See Query Splitting for patterns to flatten and separate expensive queries.

Exporting a Full Product Catalog

You need all 10,000+ products with variants. Switch from paginated queries to a bulk operation that bypasses the cost system entirely.

See Bulk Operations for the complete mutation, polling, and JSONL download flow.

Resources

• GraphQL Rate Limits
• Calculated Query Cost
• Bulk Operations
• Query Cost Debugging