# Shopify Performance Tuning

> 'Optimize Shopify API performance with GraphQL query cost reduction, bulk operations, caching strategies, and Storefront API for high-traffic storefronts. Use when queries are slow or hitting THROTTLED errors, exporting large datasets, or optimizing API throughput for a high-traffic storefront. Trigger with phrases like "shopify performance", "optimize shopify", "shopify slow", "shopify caching", "shopify bulk operation", "shopify query cost". '

- Skill: `jeremylongshore/shopify-performance-tuning` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add jeremylongshore/shopify-performance-tuning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeremylongshore/shopify-performance-tuning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jeremylongshore (https://skillmd.com/u/jeremylongshore)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/jeremylongshore/shopify-performance-tuning

---


# Shopify Performance Tuning

## Overview

Optimize Shopify API performance through GraphQL query cost reduction, bulk operations for large data exports, response caching, and Storefront API for high-traffic public-facing queries.

## Prerequisites

- Understanding of Shopify's calculated query cost system
- Access to the `Shopify-GraphQL-Cost-Debug: 1` header for cost analysis
- Redis or in-memory cache available (optional)

## Instructions

### Step 1: Analyze and Reduce Query Cost

Use the debug header to inspect `requestedQueryCost` vs `actualQueryCost`. Reduce cost by selecting only needed fields and lowering `first:` page sizes (250 to 50 can cut cost by 5x).

See [Query Cost Optimization](references/query-cost-optimization.md) for debug commands and before/after examples.

### Step 2: Use Bulk Operations for Large Exports

Bulk operations bypass rate limits and are designed for exporting large datasets. Start a mutation, poll for completion, then download JSONL results.

See [Bulk Operations](references/bulk-operations.md) for the complete mutation/poll/download flow and performance comparison table.

### Step 3: Cache Frequently Accessed Data

LRU cache layer with webhook-driven invalidation. Cache product data for 5 minutes, then clear on `products/update` webhook events.

See [Response Caching](references/response-caching.md) for the complete implementation.

### Step 4: Use Storefront API for Public Queries

The Storefront API has separate rate limits and is designed for high-traffic public storefronts. Uses `LATEST_API_VERSION` from `@shopify/shopify-api`.

See [Storefront API Usage](references/storefront-api-usage.md) for the complete implementation.

## Output

- Query costs reduced through field selection and page size optimization
- Bulk operations configured for large data exports
- Response caching with webhook-driven invalidation
- Storefront API used for public-facing high-traffic queries

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| `THROTTLED` on every query | `requestedQueryCost` too high | Reduce `first:` and remove unused fields |
| Bulk operation FAILED | Query syntax error | Test query in GraphiQL first |
| Stale cache data | Cache not invalidated | Add webhook handlers to clear cache |
| Storefront API 403 | Wrong token type | Use Storefront API access token, not Admin |

## Examples

### Reducing Query Cost on a Product Sync

A product sync job hits THROTTLED errors. Analyze the cost breakdown, reduce `first:` page sizes, and remove unused fields.

See [Query Cost Optimization](references/query-cost-optimization.md) for debug commands and before/after examples.

### Exporting Orders with Bulk Operations

Export 50,000 orders with line items using a bulk operation that bypasses rate limits and returns JSONL results.

See [Bulk Operations](references/bulk-operations.md) for the complete mutation, polling, and download flow.

### Caching Product Data with Webhook Invalidation

Add an LRU cache layer for product queries that auto-invalidates when `products/update` webhook events fire.

See [Response Caching](references/response-caching.md) for the complete caching implementation.

## Resources

- [GraphQL Rate Limits](https://shopify.dev/docs/api/usage/rate-limits#graphql-admin-api-rate-limits)
- [Bulk Operations](https://shopify.dev/docs/api/usage/bulk-operations/queries)
- [Storefront API](https://shopify.dev/docs/api/storefront)
- [Query Cost Debug Header](https://shopify.dev/docs/api/usage/rate-limits#query-cost)

---

**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `skills/.curated/shopify-performance-tuning/SKILL.md`

**Also appears in:** `jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/shopify-pack/skills/shopify-performance-tuning/SKILL.md`