shopify-graphql-cost-optimizer

name	shopify-graphql-cost-optimizer
description	Master Shopify's calculated query cost system to avoid throttling. Use when hitting THROTTLED errors, optimizing GraphQL queries, or deciding when to use bulk operations instead. Trigger with phrases like "shopify query cost", "shopify graphql cost", "shopify rate limit graphql", "shopify throttled", "shopify bulk operations".
allowed-tools	Read, Write, Edit, Bash(npm:*), Grep
version	2.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","ecommerce","shopify"]
compatibility	Designed for Claude Code

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 is the worst-case estimate, while actualQueryCost is what you really paid. Understanding the gap between them is how you avoid throttling.

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 request header for a per-field cost breakdown.

Step 2: Predict Query Cost

Cost rules for calculation:

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