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".
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.
@shopify/shopify-api package installedEvery 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.
Cost rules for calculation:
shop { name } = 1)first or last param multiplied by child cost, plus 2 for the connection itself# 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.
Reduce first parameter — the single biggest lever:
# 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.
When you need 250+ items, switch to bulkOperationRunQuery. It bypasses the cost system entirely — no first/last params, no cursors, returns all items as JSONL.
See references/bulk-operations.md for the complete bulkOperationRunQuery mutation, polling, and JSONL download flow.
extensions.cost| Error | Cause | Solution |
|---|---|---|
THROTTLED | Bucket depleted (0 points available) | Wait for restoreRate to refill, then retry |
MAX_COST_EXCEEDED | Single query exceeds 1,000 points | Reduce first params or split into multiple queries |
QUERY_TOO_COMPLEX | Too many nested connections (depth > 3) | Flatten query, fetch nested data separately |
BULK_OPERATION_FAILED | Bulk query syntax error or timeout | Check errorCode on the bulk operation object |
BULK_OPERATION_ALREADY_RUNNING | Only one bulk op per app per store | Poll current operation status before starting new one |
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.
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.
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.