Shopify Advanced Troubleshooting

Overview

Deep debugging for complex Shopify API issues: cost analysis with debug headers, webhook delivery inspection, GraphQL query introspection, and systematic isolation of intermittent failures.

Prerequisites

• Access to Shopify admin and Partner Dashboard
• Familiarity with GraphQL and HTTP debugging
• curl and jq available

Instructions

Step 1: GraphQL Cost Analysis

When queries THROTTLE unexpectedly, use the cost debug header by adding Shopify-GraphQL-Cost-Debug: 1 to your request. The response extensions.cost reveals why a query is expensive.

Key: requestedQueryCost is first multiplied through nested connections. 50 products * 20 variants * (1 + 5 metafields) = high cost even if actual data is small.

Step 2: Trace a Specific Request

Every Shopify response includes X-Request-Id. Capture it for support escalation:

curl -v -X POST "https://$STORE/admin/api/2025-04/graphql.json" \
  -H "X-Shopify-Access-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ shop { name } }"}' 2>&1 | tee /tmp/shopify-debug.txt

grep -i "x-request-id" /tmp/shopify-debug.txt

Step 3: Webhook Delivery Inspection

Inspect webhook delivery status in the Partner Dashboard, or query subscription health via API.

See Webhook Status Query for the complete query and common delivery failure patterns.

Step 4: GraphQL Introspection for API Version Differences

Use introspection queries to check if specific fields or mutations exist in your API version. Query __type for field lists or __schema for available mutations filtered by prefix.

Step 5: Systematic Isolation

Run a layer-by-layer diagnostic that tests DNS, TCP, TLS, HTTP, GraphQL, and rate limit state independently.

See Layer-by-Layer Diagnostic for the complete shell script.

Step 6: Debug Intermittent Failures

Wrap Shopify calls in a debug logger that captures timing, cost, and error data for pattern analysis.

See Debug Intermittent Failures for the complete TypeScript implementation.

Output

• Query cost breakdown identifying expensive fields
• Request IDs captured for Shopify support
• Webhook delivery health verified
• Layer-by-layer isolation identifying failure point
• Debug log with timing patterns for intermittent issues

Error Handling

Shopify AI Toolkit Wrapper

Overview

Shopify's AI Toolkit provides an official MCP (Model Context Protocol) server for developer workflows. This skill configures it for Claude Code, enabling GraphQL schema validation, Liquid template linting, and real-time Shopify documentation search without leaving your editor.

Prerequisites

• Node.js 18+ and npm/pnpm installed
• A Shopify store with a custom app or API access token
• Access scopes appropriate for your workflow (minimum: read_products, read_themes)
• Claude Code with MCP support enabled

Instructions

Step 1: MCP Configuration

Create or update .mcp.json in your project root:

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "-y",
        "@shopify/ai-toolkit-mcp"
      ],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "${SHOPIFY_ACCESS_TOKEN}",
        "SHOPIFY_STORE_URL": "https://your-store.myshopify.com"
      }
    }
  }
}

> Note: The package name @shopify/ai-toolkit-mcp may change. Check shopify.dev/docs for the latest official MCP package name and configuration.

Set your environment variables:

export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxxxxxxxxx"
export SHOPIFY_STORE_URL="https://your-store.myshopify.com"

See references/mcp-config.md for advanced configuration and troubleshooting.

Step 2: GraphQL Schema Validation

With the MCP server running, validate GraphQL queries against your store's live schema before executing them. The MCP introspects the schema and catches:

• Deprecated fields (e.g., priceRange should be priceRangeV2)
• Type mismatches in mutation inputs (e.g., ProductInput split into ProductCreateInput/ProductUpdateInput in 2024-10)
• Missing required fields and incorrect enum values

See references/graphql-validation.md for common validation errors and deprecated field mappings.

Step 3: Liquid Template Linting

The AI Toolkit checks Liquid templates for syntax errors, deprecated filters, and performance anti-patterns:

Shopify Architecture Variants

Overview

Four validated architecture patterns for building on Shopify. Choose based on your use case: embedded admin app, headless storefront, backend integration, or theme extension.

Prerequisites

• Clear understanding of what you're building
• Knowledge of your target merchants
• Understanding of Shopify's app ecosystem

Instructions

Variant A: Embedded Admin App (Remix)

Admin panel apps, merchant tools, dashboards. Uses @shopify/shopify-app-remix with OAuth and Polaris UI inside the Shopify admin.

See Embedded Remix App for the project structure and authenticated loader pattern.

Variant B: Headless Storefront (Hydrogen)

Custom storefronts and unique shopping experiences. Uses the Storefront GraphQL API, hosted on Shopify Oxygen or any edge platform.

See Hydrogen Storefront for the project structure and Storefront API loader.

Variant C: Backend Integration (Standalone)

ERP sync, warehouse management, analytics. Uses @shopify/shopify-api with a custom app access token -- no OAuth or merchant UI needed.

See Backend Integration for the project structure and client setup.

Variant D: Theme App Extension Only

Storefront widgets, product reviews, badges. Runs entirely in the merchant's storefront using Liquid templates -- no server needed.

See Theme App Extension for the project structure and Liquid block example.

Decision Matrix

Output

• Architecture v…

Shopify B2B & Wholesale

Overview

Shopify Plus B2B features let you create separate wholesale experiences with company accounts, custom catalogs, and tiered pricing. This skill covers the full B2B setup: companies, catalogs, price lists, and checkout configuration using the GraphQL Admin API. Requires a Shopify Plus plan.

Prerequisites

• Shopify Plus plan (B2B features are Plus-only)
• Access scopes: read_customers, write_customers, read_products, write_products, read_orders
• B2B enabled in Shopify admin (Settings > B2B)
• API version 2023-10 or later (B2B mutations stabilized)

Instructions

Step 1: Create a B2B Company

Use companyCreate with CompanyCreateInput — requires company (name, note), companyContact (email, firstName, lastName), and companyLocation (name, billingAddress, shippingAddress):

await client.request(COMPANY_CREATE, {
  variables: {
    input: {
      company: { name: "Acme Wholesale Inc", note: "Tier 1 partner" },
      companyContact: { email: "buyer@acme.com", firstName: "Jane", lastName: "Doe" },
      companyLocation: {
        name: "Headquarters",
        billingAddress: { address1: "123 Commerce St", city: "Austin", provinceCode: "TX", countryCode: "US", zip: "78701" },
        shippingAddress: { address1: "123 Commerce St", city: "Austin", provinceCode: "TX", countryCode: "US", zip: "78701" },
      },
    },
  },
});
// Always check userErrors in response — returns code like COMPANY_NOT_FOUND, INVALID

See references/company-management.md for the full mutation, additional contacts, locations, and roles.

Step 2: Create a Catalog

Catalogs link products to specific companies. Use catalogCreate with a title, status, and context.companyLocationIds:

await client.request(CATALOG_CREATE, {
  variables: {
    input: {
      title: "Wholesale Tier 1",
      status: "ACTIVE",
      context: { companyLocationIds: ["gid://shopify/CompanyLocation/123456"] },
    },
  },
});

Step 3: Set Wholesale Pricing

Create a price list with priceListCreate. Use PERCENTAGE_DECREASE for blanket discounts or priceListFixedPricesAdd for per-variant overrides:

// 30% off all products in this catalog
await client.request(PRICE_LIST_CREATE, {
  variables: {
    input: {
      name: "Wholesale 30% Off",
      currency: "USD",
…

Shopify Checkout UI Extensions

Overview

Checkout UI Extensions replace checkout.liquid (deprecated August 2025) with sandboxed, React-like components at specific checkout targets. They run in isolation with no DOM access and a strict 64KB bundle limit, using Shopify's component library for consistent, accessible UIs.

Prerequisites

• Shopify CLI 3.x+ and a Shopify Partners app
• Node.js 18+, @shopify/ui-extensions-react package
• Development store with checkout extensibility enabled

Instructions

Step 1: Configure the Extension

# extensions/checkout-banner/shopify.extension.toml
api_version = "2025-01"
type = "ui_extension"

[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "purchase.checkout.block.render"

[extensions.capabilities]
api_access = true
network_access = false

Step 2: Build with UI Components

import {
  reactExtension, Banner, BlockStack, Text, useSettings,
} from "@shopify/ui-extensions-react/checkout";

export default reactExtension("purchase.checkout.block.render", () => <CheckoutBanner />);

function CheckoutBanner() {
  const { banner_text } = useSettings();
  return (
    <BlockStack spacing="tight">
      <Banner status="info">{banner_text || "Free shipping over $50!"}</Banner>
    </BlockStack>
  );
}

Step 3: Read Checkout Data with Hooks

import {
  useApplyMetafieldsChange, useTotalAmount, useShippingAddress, TextField,
} from "@shopify/ui-extensions-react/checkout";

function DeliveryNote() {
  const applyMetafieldsChange = useApplyMetafieldsChange();
  return (
    <TextField
      label="Delivery instructions"
      onChange={(value) => applyMetafieldsChange({
        type: "updateMetafield",
        namespace: "custom", key: "delivery_note",
        valueType: "string", value,
      })}
    />
  );
}

Step 4: Bundle Size Strategies

shopify app build --verbose  # Check output size
# Import only what you use — each component adds ~1-3KB
# Avoid lodash, date-fns, zod — use native JS
# Split into multiple extensions if approaching 64KB

See extension-targets.md for all targets, ui-components.md for components, and bundle-optimization.md for size strategies.

Output

• Checkout UI extension rendering at the configured target point
• Custom data collection via metafield writes from checkout
• Merchant-configurable settings via the extension editor
• S…

Shopify CI Integration

Overview

Set up CI/CD pipelines for Shopify apps using GitHub Actions, including API version compatibility testing, Shopify CLI deployment, and extension validation.

Prerequisites

• GitHub repository with Actions enabled
• Shopify Partner account with CLI access
• Test store access token for integration tests

Instructions

Step 1: GitHub Actions Workflow

Create a workflow with lint, test, API version check, and deploy jobs.

See GitHub Actions Workflow for the complete .github/workflows/shopify-ci.yml file.

Step 2: Configure Secrets

# Store these in GitHub repository secrets
gh secret set SHOPIFY_API_KEY --body "your_api_key"
gh secret set SHOPIFY_API_SECRET --body "your_api_secret"
gh secret set SHOPIFY_TEST_STORE --body "your-dev-store.myshopify.com"
gh secret set SHOPIFY_TEST_TOKEN --body "shpat_test_token"
gh secret set SHOPIFY_PARTNERS_TOKEN --body "your_partners_cli_token"

Step 3: Integration Test Structure

Write integration tests that verify store connectivity, required scopes, and rate limit compliance. Tests skip automatically when SHOPIFY_ACCESS_TOKEN is not set.

See Integration Test Structure for the complete Vitest test file.

Output

• CI pipeline with lint, typecheck, unit tests, and integration tests
• API version deprecation monitoring
• Automated deployment via Shopify CLI
• Integration tests running against a test store

Error Handling

Examples

Shopify CLI Token for CI

# Generate a CLI token for CI (no interactive login needed)
# Go to: partners.shopify.com > Settings > CLI tokens
# Create a new token and save as SHOPIFY_PARTNERS_TOKEN secret

Resources

• Shopify CLI for CI/CD
• GitHub Actions Documentation
• Shopify App Deployment

Shopify Common Errors

Overview

Quick-reference guide for the most common Shopify API errors with real error messages, causes, and fixes.

Prerequisites

• Shopify app with API credentials configured
• Access to application logs or console output

Instructions

Step 1: Identify the Error Type

Check whether the error is an HTTP status code error or a GraphQL userErrors response.

Step 2: Match Error Below and Apply Fix

401 Unauthorized

Response: "[API] Invalid API key or access token (unrecognized login or wrong password)"

Causes: Access token expired (merchant uninstalled/reinstalled), wrong header, or using Storefront token for Admin API.

Fix: Verify token format (shpat_ + 32 hex chars) and test with a simple shop.json GET request.

403 Forbidden

Response: "This action requires merchant approval for read_orders scope."

Fix: Add the needed scope to shopify.app.toml under [access_scopes] and re-trigger OAuth.

404 Not Found

Causes: Wrong API version in URL, resource was deleted, or store domain is incorrect.

Fix: Verify the API version exists by checking /admin/api/versions.json.

422 Unprocessable Entity

Common triggers: Missing required fields, duplicate handle/slug, invalid metafield type, price format issues (must be string like "29.99"), invalid country/province codes.

Fix: Check the errors object or userErrors array for specific field-level messages.

429 Too Many Requests (Rate Limited)

REST returns 429 with Retry-After header. GraphQL returns 200 with THROTTLED error code in the body and zero currentlyAvailable points.

Fix: See shopify-rate-limits skill for complete backoff implementation.

GraphQL userErrors (200 with Errors)

Critical: Shopify returns HTTP 200 even when mutations fail. Always check userErrors after every mutation:

const result = response.data.productCreate;
if (result.userErrors.length > 0) {
  for (const err of result.userErrors) {
    console.error(`Field ${err.field?.join(".")}: ${err.message} (${err.code})`);
  }
  throw new Error("Shopify validation failed");
}

5xx Server Errors

Shopify internal errors -- not your fault. Retry with exponential backoff and capture the X-Request-Id header for support tickets.

Output

Shopify Products & Catalog Management

Overview

Primary workflow for Shopify: manage products, variants, collections, and inventory using the GraphQL Admin API. Covers CRUD operations with real API mutations and response shapes.

Prerequisites

• Completed shopify-install-auth setup
• Access scopes: read_products, write_products, read_inventory, write_inventory
• API version 2024-10 or later (ProductInput was split in this version)

Instructions

Step 1: Create a Product

Use productCreate with ProductCreateInput (as of 2024-10, this replaced the old unified ProductInput). Always check userErrors -- Shopify returns 200 even on validation failures.

See Product Create Mutation for the complete mutation, variables, and error handling.

Step 2: Update a Product

Use productUpdate with ProductUpdateInput (separate from create as of 2024-10). Supports metafield updates inline.

See Product Update Mutation for the complete mutation and variables.

Step 3: Query Products with Filtering

Search products using Shopify's query syntax (status:active, product_type:Apparel AND vendor:'My Brand', tag:sale, etc.) with cursor-based pagination.

See Search Products Query for the complete query with pagination and query syntax examples.

Step 4: Manage Variants and Pricing

Create variants in bulk with productVariantsBulkCreate, including pricing, SKU, barcode, option values, and inventory quantities per location.

See Bulk Create Variants for the complete mutation and variables.

Step 5: Manage Collections

Create smart (automated) collections with rule-based product matching using tag, product type, and other column filters.

See Smart Collection Create for the complete mutation and variables.

Output

• Product created with variants and options
• Products queryable with search filters
• Variant pricing and inventory configured
• Smart collections auto-organizing products

Error Handling

Shopify Orders & Customer Management

Overview

Secondary core workflow: manage orders, customers, and fulfillments. Query order data, process fulfillments, and handle customer records through the GraphQL Admin API.

Prerequisites

• Completed shopify-install-auth setup
• Access scopes: read_orders, write_orders, read_customers, write_customers, read_fulfillments, write_fulfillments
• Familiarity with shopify-core-workflow-a (products)

Instructions

Step 1: Query Orders

Query orders with financial/fulfillment status filters, line items, customer data, and shipping addresses. Uses Shopify query syntax (financial_status:paid, fulfillment_status:unfulfilled, name:#1001, etc.).

See Query Orders for the complete query with pagination and query syntax examples.

Step 2: Create a Draft Order

Create draft orders with variant line items, custom line items, discounts, shipping addresses, and customer assignment.

See Draft Order Create for the complete mutation and variables.

Step 3: Process Fulfillment

Two-step process: first query fulfillment orders for an order to get line item IDs, then create the fulfillment with tracking information and customer notification.

See Fulfillment Processing for both queries and the complete workflow.

Step 4: Customer Management

Search customers by email, order count, total spent, tags, and state. Returns addresses and metafields.

See Customer Search Query for the complete query and syntax examples.

Output

• Orders queryable with financial and fulfillment status filters
• Draft orders created with line items, discounts, and shipping
• Fulfillments processed with tracking information
• Customer records searchable with spending and order filters

Error Handling

Shopify Cost Tuning

Overview

Optimize Shopify app and API costs through plan analysis, API usage monitoring, and strategies to minimize billable API calls. Covers Shopify store plans, Partner app billing, and API efficiency.

Prerequisites

• Access to Shopify Partner Dashboard for app billing
• Understanding of current API usage patterns
• Knowledge of merchant's Shopify plan

Instructions

Step 1: Understand Shopify Plan Rate Limits

API rate limits are determined by the merchant's plan, not your app:

Key insight: Upgrading from Basic to Advanced doesn't help rate limits. Only Plus doubles them.

Step 2: App Billing API

If your app charges merchants, use the GraphQL appSubscriptionCreate mutation to create recurring charges. Set test: true in development to avoid real billing.

See App Billing API for the complete mutation and variable setup.

Step 3: Monitor API Usage

Track GraphQL query costs and REST call counts over time to identify optimization opportunities. Log extensions.cost.actualQueryCost from every GraphQL response.

See Usage Tracker Class for a complete tracking implementation with reporting.

Step 4: Cost Reduction Strategies

Four key strategies: replace REST with GraphQL for targeted field selection, use bulk operations for exports, cache responses and invalidate via webhooks, and use Storefront API for public data.

See Cost Reduction Strategies for code examples of each approach.

Output

• API usage monitored with cost tracking
• Rate limit-efficient query patterns
• App billing configured (if charging merchants)
• Cost reduction strategies applied

Error Handling

Shopify Data Handling

Overview

Handle customer PII correctly when building Shopify apps. Covers the mandatory GDPR webhooks, data minimization, and the specific privacy requirements Shopify enforces for App Store submission.

Prerequisites

• Understanding of GDPR/CCPA requirements
• Shopify app with webhook handling configured
• Database for storing and deleting customer data

Instructions

Step 1: Understand What Data Shopify Shares

When a merchant grants your app access, you may receive:

Step 2: Implement Mandatory Privacy Webhooks

Shopify requires three GDPR webhooks for App Store apps. Your app will be rejected without them: customers/data_request (customer wants their data), customers/redact (delete a customer's PII), and shop/redact (delete all shop data 48h after uninstall).

See GDPR Privacy Webhooks for the complete implementation of all three handlers.

Step 3: Data Minimization and PII Detection

Only fetch the fields you actually use in GraphQL queries. Add PII redaction middleware to prevent customer data from leaking into logs — detect emails, phone numbers, and credit card patterns.

See Data Minimization and PII Detection for query examples and redaction middleware.

Step 4: Data Retention Policy

Automate cleanup with a daily cron job: delete API logs after 30 days, webhook logs after 90 days, and keep audit logs for 7 years (regulatory requirement).

See Data Retention Policy for the complete implementation.

Output

• GDPR mandatory webhooks implemented and tested
• Data minimization in API queries
• PII redaction in all log output
• Retention policy with automatic cleanup

Error Handling

Shopify Debug Bundle

Overview

Collect all diagnostic information needed for Shopify support tickets: API version compatibility, access scopes, rate limit state, recent errors, and connectivity checks.

Prerequisites

• Shopify access token (shpat_xxx) available
• curl and jq installed
• Store domain known (*.myshopify.com)

Instructions

Step 1: Create and Run Debug Bundle

The debug bundle script collects shop info, access scopes, supported API versions, GraphQL and REST rate limit state, environment details (Node/npm versions, SDK version, env vars), then packages everything into a tarball with tokens automatically redacted.

See Debug Bundle Script for the complete bash script.

Set these environment variables before running:

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="shpat_xxx"
export SHOPIFY_API_VERSION="2025-04"  # Update quarterly — see shopify.dev/docs/api/usage/versioning

Output

• shopify-debug-YYYYMMDD-HHMMSS.tar.gz containing:
• summary.txt — shop info, scopes, API versions, rate limits, environment
• All secrets automatically redacted

Error Handling

Examples

Sensitive Data Checklist

ALWAYS REDACT before sharing:

• Access tokens (shpat_xxx)
• API keys and secrets
• Customer PII (emails, names, addresses)
• Order details with customer data

Safe to include:

• Store name and plan
• API version and scopes
• Error messages and X-Request-Id values
• Rate limit headers
• SDK/runtime versions

Quick One-Liner Health Check

curl -sf -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  "https://$SHOPIFY_STORE/admin/api/2025-04/shop.json" \
  | jq '{name: .shop.name, plan: .shop.plan_name}' \
  && echo "HEALTHY" || echo "UNHEALTHY"

Resources

• …

Shopify Deploy Integration

Overview

Deploy Shopify apps to popular hosting platforms. Covers environment configuration, webhook URL setup, and Shopify CLI deployment for extensions.

Prerequisites

• Shopify app tested locally with shopify app dev
• Platform CLI installed (vercel, fly, or gcloud)
• Production API credentials ready
• shopify.app.toml configured

Instructions

Step 1: Deploy App with Shopify CLI

# Shopify CLI handles extension deployment and app config sync
shopify app deploy

# This uploads:
# - Theme app extensions
# - Function extensions
# - App configuration (URLs, scopes, webhooks)
# But NOT your web app — you host that separately

Step 2: Vercel Deployment

Set environment variables, configure vercel.json for webhooks and function timeouts, and update shopify.app.toml with the Vercel URL.

See Vercel Deployment for the complete configuration.

Step 3: Fly.io Deployment

Configure fly.toml with health checks and min-machines, set secrets via fly secrets set, and deploy.

See Fly.io Deployment for the complete configuration.

Step 4: Google Cloud Run Deployment

Use a multi-stage Dockerfile for minimal image size, deploy with gcloud run deploy, and configure secrets via Secret Manager.

See Cloud Run Deployment for Dockerfile and deploy commands.

Step 5: Post-Deploy Verification

Run health checks, verify webhook endpoints return 401 (no HMAC), test OAuth start, and sync app config.

See Post-Deploy Verification for the complete verification script.

Output

• App deployed to production hosting
• Environment variables securely configured
• Webhook endpoints accessible via HTTPS
• Health check passing
• App URLs synced to Shopify Partner Dashboard

Error Handling

Shopify Enterprise RBAC

Overview

Implement role-based access control for Shopify Plus apps using Shopify's staff member permissions, multi-location features, and Organization-level access.

Prerequisites

• Shopify Plus store (for Organization features)
• Understanding of Shopify's staff permission model
• read_users scope for querying staff permissions

Instructions

Step 1: Query Staff Permissions and Map to App Roles

Query staff members via GraphQL to get their access scopes, then map those scopes to app-level roles (admin, manager, fulfillment, viewer). Staff permissions mirror app scopes like read_products, write_orders, etc.

See Staff Query and Role Mapping for the complete GraphQL query, role definitions, and matching logic.

Step 2: Permission Middleware and Multi-Location Access

In embedded apps, use online access tokens to get per-staff permissions from session.onlineAccessInfo. For Shopify Plus stores with multiple locations, restrict fulfillment and inventory operations to authorized locations per user.

See Permission Middleware and Location Access for Remix loader examples and location access control.

Step 3: Organization API and Audit Trail

Shopify Plus Organization API enables multi-store management with organization-level, store-level admin, and store-level staff roles. Log all access decisions (allowed and denied) for compliance auditing.

See Organization API and Audit Trail for the Organization query and audit implementation.

Output

• Staff permissions queried and mapped to app roles
• Permission middleware protecting embedded app routes
• Multi-location access control for Shopify Plus
• Audit trail for all access decisions

Error Handling

Examples

Quick Permission Check in Remix

// Remix action with permission guard
export async function action({ request }: ActionFunctionArgs) {
  const { admin, session } …

Shopify Functions

Overview

Shopify Functions execute custom business logic in a WebAssembly sandbox at checkout: discounts, payment filtering, delivery customization, and cart transforms. They run server-side with strict constraints (11ms execution, 1MB memory, no network access) and replace Shopify Scripts.

Prerequisites

• Shopify CLI 3.x+ installed (npm install -g @shopify/cli)
• Shopify Partners account with a development store
• App configured for the target function API type

Instructions

Step 1: Configure the Function Extension

# extensions/product-discount/shopify.extension.toml
api_version = "2025-01"
type = "product_discounts"

[[targeting]]
target = "purchase.product-discount.run"
input_query = "extensions/product-discount/input.graphql"
export = "run"

Step 2: Define the Input Query

The input query declares what data your function receives at runtime:

# extensions/product-discount/input.graphql
query Input {
  cart {
    lines {
      quantity
      merchandise {
        ... on ProductVariant {
          id
          product { hasAnyTag(tags: ["VIP-DISCOUNT"]) }
        }
      }
    }
  }
  discountNode {
    metafield(namespace: "$app:discount-config", key: "percentage") { value }
  }
}

Step 3: Implement the Function

// extensions/product-discount/src/run.ts
import type { Input, FunctionRunResult } from "../generated/api";

export function run(input: Input): FunctionRunResult {
  const percentage = parseFloat(input.discountNode?.metafield?.value ?? "0");
  if (percentage === 0) return { discounts: [], discountApplicationStrategy: "FIRST" };

  const targets = input.cart.lines
    .filter((line) => line.merchandise.product.hasAnyTag)
    .map((line) => ({ productVariant: { id: line.merchandise.id } }));

  return {
    discounts: [{
      targets,
      value: { percentage: { value: percentage.toString() } },
      message: `${percentage}% VIP Discount`,
    }],
    discountApplicationStrategy: "FIRST",
  };
}

Step 4: Test and Deploy

shopify app function typegen          # Generate types from input query
shopify app function build            # Build to WASM
shopify app function run --input test-input.json  # Test locally
shopify app deploy                    # Deploy with app

See function-types.md for all function types, input-output-schemas.md for I/O shapes, and wasm-constraints.md for sandbox limitations.

Output

• WASM binary deployed a…

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., 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 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.

…

Shopify Hello World

Overview

Minimal working example: query your store's products using the Shopify GraphQL Admin API. Uses @shopify/shopify-api with a custom app access token for zero-friction setup.

Prerequisites

• Completed shopify-install-auth setup
• A Shopify development store
• An Admin API access token (shpat_xxx) from Settings > Apps > Develop apps

Instructions

Step 1: Create Project

mkdir shopify-hello-world && cd shopify-hello-world
npm init -y
npm install @shopify/shopify-api dotenv

Step 2: Configure Environment

# .env
SHOPIFY_STORE=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret

Step 3: Write the Hello World Script

Initialize the Shopify API client with LATEST_API_VERSION (imported from @shopify/shopify-api), create a custom app session, then query shop info and products via GraphQL.

See Hello World Script for the complete implementation.

Step 4: Run It

npx tsx hello-shopify.ts
# Or compile first:
npx tsc hello-shopify.ts && node hello-shopify.js

Output

Expected console output:

Store: My Dev Store
Currency: USD

Products:
  - Classic T-Shirt (ACTIVE, 150 in stock)
      Variant: Small — $29.99 (SKU: TSH-SM)
      Variant: Medium — $29.99 (SKU: TSH-MD)
      Variant: Large — $29.99 (SKU: TSH-LG)
  - Coffee Mug (ACTIVE, 42 in stock)
      Variant: Default Title — $14.99 (SKU: MUG-01)

Success! Your Shopify connection is working.

Error Handling

Shopify Incident Runbook

Overview

Rapid incident response for Shopify API outages, authentication failures, and rate limit emergencies. Distinguish between Shopify-side issues and your app's integration issues.

Prerequisites

• Access to Shopify admin and status page
• Application logs and metrics
• Communication channels (Slack, PagerDuty)

Instructions

Step 1: Quick Triage (First 5 Minutes)

Run the triage script to check Shopify status, API connectivity, REST rate limits, and GraphQL throttle state in one pass.

See Triage Script for the complete diagnostic script.

Step 2: Decision Tree

Is Shopifystatus.com showing an incident?
├── YES → Shopify-side outage
│   ├── Enable graceful degradation / cached responses
│   ├── Notify stakeholders: "Shopify is experiencing issues"
│   └── Monitor status page for resolution
│
└── NO → Likely your integration
    ├── HTTP 401? → Token expired or revoked
    │   └── Check: Was app reinstalled? Rotate token.
    ├── HTTP 403? → Scope missing
    │   └── Check: Were scopes changed? Re-run OAuth.
    ├── HTTP 429 / THROTTLED? → Rate limit exceeded
    │   └── Check: Runaway loop? Reduce query frequency.
    ├── HTTP 5xx? → Intermittent Shopify issue
    │   └── Retry with backoff, monitor for pattern.
    └── Network timeout? → Infrastructure issue
        └── Check: DNS, firewall, TLS certificates.

Step 3: Immediate Actions by Error Type

Diagnostic commands and remediation for 401 (token expired), 429 (rate limited), and 5xx (Shopify internal errors). Always capture X-Request-Id headers for Shopify support.

See Error Type Actions for complete commands per error type.

Step 4: Communication Templates

Internal (Slack):

INCIDENT: Shopify Integration Issue
Severity: P[1/2/3]
Status: INVESTIGATING
Impact: [What users/merchants are affected]
Root cause: [Shopify outage / Our auth issue / Rate limiting]
Action: [What we're doing now]
Next update: [Time]
Responder: @[name]

External (Merchant-facing):

We're currently experiencing issues with some Shopify-connected features.
[Order sync / Product updates / etc.] may be delayed.
We're actively working on resolution and will update shortly.
All data is safe — no orders or products have been lost.

Output

• Triage completed within 5 minutes
• Root cause identified (Shopify vs. integration)
• Immediate mitigation applied
• Stakeholders notified

Error Handling

Shopify Install & Auth

Overview

Set up Shopify app authentication using the official @shopify/shopify-api library. Covers OAuth flow, session token exchange, custom app tokens, and Storefront API access.

Prerequisites

• Node.js 18+ (the @shopify/shopify-api v9+ requires it)
• A Shopify Partner account at https://partners.shopify.com
• An app created in the Partner Dashboard with API credentials
• A development store for testing

Instructions

Step 1: Install the Shopify API Library

# Core library + Node.js runtime adapter
npm install @shopify/shopify-api @shopify/shopify-app-remix
# Or for standalone Node apps:
npm install @shopify/shopify-api @shopify/shopify-app-express

# For Remix (recommended by Shopify):
npm install @shopify/shopify-app-remix @shopify/app-bridge-react

Step 2: Configure Environment Variables

Create a .env file (add to .gitignore immediately):

# .env — NEVER commit this file
SHOPIFY_API_KEY=your_app_api_key
SHOPIFY_API_SECRET=your_app_api_secret
SHOPIFY_SCOPES=read_products,write_products,read_orders,write_orders
SHOPIFY_APP_URL=https://your-app.example.com
SHOPIFY_HOST_NAME=your-app.example.com

# For custom/private apps only:
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx

# API version — use a stable quarterly release
# Update quarterly — see shopify.dev/docs/api/usage/versioning
SHOPIFY_API_VERSION=2025-04

# .gitignore — add these immediately
.env
.env.local
.env.*.local

Step 3: Initialize the Shopify API Library

// src/shopify.ts
import "@shopify/shopify-api/adapters/node";
import { shopifyApi, LATEST_API_VERSION, Session } from "@shopify/shopify-api";

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  scopes: process.env.SHOPIFY_SCOPES!.split(","),
  hostName: process.env.SHOPIFY_HOST_NAME!,
  apiVersion: LATEST_API_VERSION,
  isEmbeddedApp: true,
});

export default shopify;

Step 4: Implement OAuth Flow (Public Apps)

Express-based OAuth flow that redirects to Shopify and handles the callback token exchange.

See OAuth Flow for the complete Express route implementation.

Step 5: Token Exchange (Embedded Apps)

For embedded apps, use session token exchange instead of traditional OAuth:

// Token exchange — converts session token (JWT) to API access token
import shopify from "../shopify";

async function exchangeToken(
  shop: string,
  sessionToken: string
): Promise<Session> {
  const { session } = await shopify.auth.tokenExchange({
    sessi…

Shopify Known Pitfalls

Overview

The 10 most common mistakes when building Shopify apps, with real API examples showing the wrong way and the right way.

Prerequisites

• Existing Shopify app codebase to review or audit
• Familiarity with GraphQL Admin API query patterns and response shapes
• Access scopes configured for the APIs your app uses
• @shopify/shopify-api v9+ installed (for code examples)

Instructions

Each pitfall includes a wrong-way and right-way code example. See Pitfall Examples for all 10 complete code comparisons.

Pitfall #1: Not Checking userErrors (The #1 Mistake)

Shopify GraphQL mutations return HTTP 200 even when they fail. The errors are in userErrors. Always check userErrors.length > 0 before accessing the result.

Pitfall #2: Using REST When GraphQL Is Required

REST Admin API is legacy as of October 2024. New public apps after April 2025 must use GraphQL. GraphQL also lets you request only the fields you need.

Pitfall #3: Ignoring API Version Deprecation

Shopify deprecates API versions ~12 months after release. Use LATEST_API_VERSION from @shopify/shopify-api and monitor x-shopify-api-deprecated-reason response headers.

Pitfall #4: Missing Mandatory GDPR Webhooks

Your app will be rejected from the App Store without customers/data_request, customers/redact, and shop/redact webhook handlers.

Pitfall #5: Webhook Handler Takes Too Long

Shopify expects a 200 response within 5 seconds. Respond immediately and queue work asynchronously, otherwise Shopify retries and creates duplicates.

Pitfall #6: Using ProductInput on API 2024-10+

The ProductInput type was split into ProductCreateInput and ProductUpdateInput in 2024-10. Use the specific type for each operation.

Pitfall #7: Not Using Cursor Pagination

Shopify uses Relay-style cursor pagination, not page numbers. Use after / endCursor with pageInfo.

Pitfall #8: Requesting 250 Items Per Page

first: 250 with nested connections creates enormous query costs that THROTTLE immediately. Use first: 50 or smaller with nested resources.

Pitfall #9: Exposing Admin Token in Client-Side Code

Admin API tokens have full access. Never send them to the browser — proxy through your server.

Pitfall #10: Not Handling APP_UNINSTALLED Webhook

When a merchant uninstalls your app, clean up sessions immediately. Stale sessions cause auth redirect loops on reinstall.

Output

• Anti-patterns identified in codebase
• Fixes prioritized (se…

Shopify Load & Scale

Overview

Load test Shopify app integrations while respecting API rate limits. Plan capacity for high-traffic events like Black Friday / Cyber Monday (BFCM).

Prerequisites

• k6 load testing tool installed (brew install k6)
• Test store with API access (never load test production)
• Understanding of Shopify rate limits per plan

Instructions

Step 1: Understand Capacity Constraints

Your app's throughput is bounded by Shopify's rate limits, not your infrastructure:

A typical product query costs 10-50 points. At 50 points/query, Standard supports ~1 query/second sustained.

Step 2: k6 Load Test Script

k6 script with Shopify-specific custom metrics (throttle tracking, query cost trends, error rates) and automatic request pacing.

See k6 Load Test Script for the complete test script.

Step 3: Run Load Test

# Against a test store — NEVER production
k6 run \
  --env SHOPIFY_STORE=dev-store.myshopify.com \
  --env SHOPIFY_ACCESS_TOKEN=shpat_test_token \
  shopify-load-test.js

# Output results to InfluxDB for Grafana dashboards
k6 run --out influxdb=http://localhost:8086/k6 shopify-load-test.js

Step 4: BFCM / Flash Sale Preparation

Pre-BFCM preparation including cache pre-warming, Storefront API offloading, bulk inventory sync, and Kubernetes HPA configuration for webhook processing.

See BFCM Preparation for application-level and infrastructure scaling patterns.

Output

• Load test script calibrated to Shopify rate limits
• Performance baseline documented
• BFCM preparation checklist completed
• Infrastructure scaling configured for webhook volume

Error Handling

Examples

Quick Capacity Estimate

Shopify Local Dev Loop

Overview

Set up a fast, reproducible local development workflow using Shopify CLI, ngrok tunneling for webhooks, and Vitest for testing against the Shopify API.

Prerequisites

• Completed shopify-install-auth setup
• Node.js 18+ with npm/pnpm
• Shopify CLI 3.x (npm install -g @shopify/cli)
• A Shopify Partner account and development store

Instructions

Step 1: Scaffold with Shopify CLI

# Create a new Remix-based Shopify app (recommended)
shopify app init

# Or scaffold manually
mkdir my-shopify-app && cd my-shopify-app
npm init -y
npm install @shopify/shopify-api @shopify/shopify-app-remix \
  @shopify/app-bridge-react @remix-run/node @remix-run/react

Step 2: Project Structure

my-shopify-app/
├── app/
│   ├── routes/
│   │   ├── app._index.tsx      # Main app page
│   │   ├── app.products.tsx    # Products management
│   │   ├── auth.$.tsx          # OAuth callback
│   │   └── webhooks.tsx        # Webhook handler
│   ├── shopify.server.ts       # Shopify API client setup
│   └── root.tsx
├── extensions/                  # Theme app extensions
├── shopify.app.toml             # App configuration
├── .env                         # Local secrets (git-ignored)
├── .env.example                 # Template for team
└── package.json

Step 3: Configure shopify.app.toml

Central app configuration with scopes, auth redirects, and mandatory GDPR webhook subscriptions.

See App TOML Config for the complete configuration file.

Step 4: Start Dev Server with Tunnel

# Shopify CLI handles ngrok tunnel + OAuth automatically
shopify app dev

# This will:
# 1. Start your app on localhost:3000
# 2. Create an ngrok tunnel
# 3. Update your app URLs in Partner Dashboard
# 4. Open your app in the dev store admin
# 5. Hot reload on file changes

Step 5: Set Up Testing

Vitest setup with mocked Shopify API client and recommended package.json scripts for the dev workflow.

See Vitest Shopify Mock for the complete test setup.

Step 6: GraphQL Explorer for Development

# Open the Shopify GraphiQL explorer for your store
# Navigate to: https://your-store.myshopify.com/admin/api/2025-04/graphql.json
# Use the Shopify Admin GraphiQL app (install from admin)

# Or use curl to test queries directly:
curl -X POST \
  "https://your-store.myshopify.com/admin/api/${SHOPIFY_API_VERSION:-2025-04}/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: shpat_xxx" \
  -d '{"query": "{ shop { name } }"}'

Output

• Shopify CLI de…

Shopify Metafields & Metaobjects

Overview

Metafields attach key-value custom data to existing resources (products, variants, orders, customers). Metaobjects define entirely new content types with custom schemas. Together they replace the need for external databases for most custom data needs.

Prerequisites

• Completed shopify-install-auth setup
• Access scopes: read_metaobjects, write_metaobjects, read_metaobject_definitions, write_metaobject_definitions
• Metafield scopes per resource: read_products/write_products for product metafields, etc.

Instructions

Step 1: Define a Metafield on Products

Use metafieldDefinitionCreate with namespace, key, type, and ownerType:

await client.request(METAFIELD_DEFINITION_CREATE, {
  variables: {
    definition: {
      namespace: "custom",
      key: "care_instructions",
      name: "Care Instructions",
      type: "multi_line_text_field",  // See references/metafield-types.md
      ownerType: "PRODUCT",
      pin: true, // Show in admin UI
    },
  },
});
// Always check userErrors — Shopify returns 200 even on validation failures

Step 2: Set Values in Batch with metafieldsSet

await client.request(METAFIELDS_SET, {
  variables: {
    metafields: [
      {
        ownerId: "gid://shopify/Product/123456",
        namespace: "custom",
        key: "care_instructions",
        value: "Machine wash cold.\nTumble dry low.",
        type: "multi_line_text_field",
      },
      // Up to 25 metafields per call
    ],
  },
});

Step 3: Create a Metaobject Definition

Define a custom content type (e.g., "Designer" with typed fields):

await client.request(METAOBJECT_DEFINITION_CREATE, {
  variables: {
    definition: {
      type: "$app:designer",
      displayNameKey: "name",
      fieldDefinitions: [
        { key: "name", name: "Name", type: "single_line_text_field" },
        { key: "bio", name: "Bio", type: "multi_line_text_field" },
        { key: "photo", name: "Photo", type: "file_reference" },
      ],
      access: { storefront: "PUBLIC_READ" },
    },
  },
});

Step 4: Create Metaobject Instances

await client.request(METAOBJECT_CREATE, {
  variables: {
    metaobject: {
      type: "$app:designer",
      handle: "jane-doe",
      fields: [
        { key: "name", value: "Jane Doe…

Shopify Migration Deep Dive

Overview

Migrate product catalogs, customers, and orders to Shopify using the GraphQL Admin API bulk mutations, CSV imports, and incremental migration patterns.

Prerequisites

• Source platform data exported (CSV, JSON, or API access)
• Shopify store with appropriate access scopes
• Scopes needed: write_products, write_customers, write_orders, write_inventory

Instructions

Step 1: Assess Migration Scope

Step 2: Bulk Product Import with productSet

productSet is idempotent — it creates or updates based on handle, making it perfect for migrations. Handles variants, metafields, and all product attributes in a single mutation.

See Product Set Migration for the complete migration function.

Step 3: Bulk Operations for Large Imports

For importing thousands of products, use Shopify's staged uploads combined with bulk mutation to avoid rate limit issues.

See Bulk Operations Import for the staged upload and bulk mutation workflow.

Step 4: Set Inventory Levels & URL Redirects

After products are created, set inventory quantities at each location and create URL redirects to preserve SEO from the old platform.

See Inventory and Redirects for both mutation implementations.

Step 5: Post-Migration Validation

Automated validation that compares expected source counts against actual Shopify counts for products, customers, and other data types.

See Post-Migration Validation for the validation script.

Output

• Products migrated with variants, images, and metafields
• Inventory levels set at correct locations
…

Shopify Multi-Environment Setup

Overview

Configure Shopify apps with isolated development, staging, and production environments. Each environment uses a separate Shopify app instance, development store, and credentials.

Prerequisites

• Shopify Partner account
• Multiple development stores (free to create in Partner Dashboard)
• Secret management solution for production (Vault, AWS Secrets Manager, etc.)

Instructions

Step 1: Create Separate App Instances

Create one app per environment in your Partner Dashboard:

Each app gets its own API_KEY, API_SECRET, and ACCESS_TOKEN.

Step 2: Environment Configuration Files

Create .env.* files for each environment and corresponding Shopify CLI TOML configs. Production secrets should never be stored on disk -- use a secret manager.

See Environment Config Files for the complete .env and .toml configuration templates.

Step 3: Environment-Aware Configuration

TypeScript config module that loads environment-specific settings (debug mode, session storage type) with LATEST_API_VERSION from @shopify/shopify-api.

See Environment-Aware Config for the complete implementation.

Step 4: Environment Guards

Safety functions that prevent dangerous operations from running in the wrong environment (e.g., blocking test data seeding in production, requiring production for billing activation).

See Environment Guards for the complete implementation.

Output

• Isolated environments with separate app instances
• Environment-specific configuration loading
• Shopify CLI configured for multi-env workflow
• Safety guards preventing cross-environment mistakes

Error Handling

Shopify Observability

Overview

Instrument your Shopify app to track GraphQL query cost, rate limit consumption, webhook delivery success, and API latency. Shopify-specific metrics that generic monitoring misses.

Prerequisites

• Prometheus or compatible metrics backend
• pino or similar structured logger
• Shopify API client with response interception

Instructions

Step 1: Shopify-Specific Metrics

Define Prometheus counters, histograms, and gauges for query cost, rate limit headroom, REST bucket state, API duration, webhook processing, and error classification.

See Shopify Metrics Definitions for the complete metric registrations.

Step 2: Instrumented GraphQL Client

Wrap the Shopify GraphQL client to automatically record query cost from extensions.cost, update rate limit gauges, and classify errors (throttled, auth, API error).

See Instrumented GraphQL Client for the complete implementation.

Step 3: REST API Header Tracking

Parse X-Shopify-Shop-Api-Call-Limit headers (e.g., "32/40") from REST responses to track leaky bucket fill level. Warn when bucket exceeds 80% capacity.

function trackRestHeaders(shop: string, headers: Record<string, string>): void {
  const callLimit = headers["x-shopify-shop-api-call-limit"];
  if (callLimit) {
    const [used, max] = callLimit.split("/").map(Number);
    restBucketGauge.set({ shop }, used);
    if (used > max * 0.8) {
      console.warn(`[shopify] REST bucket at ${used}/${max} for ${shop}`);
    }
  }
}

Step 4: Webhook Observability

Track HMAC validation results, processing success/failure, and duration for all incoming webhooks.

See Webhook Observability for the complete Express middleware.

Step 5: Structured Logging

Pino-based logger with automatic PII redaction and Shopify-specific context fields (query cost, available points, operation name).

See Structured Logging for the complete implementation.

Step 6: Alert Rules

Prometheus alert rules for low rate limits, high query cost (P95 > 500), webhook failures (> 10%), and API latency (P95 > 3s).

See Alert Rules for the complete Prometheus configuration.

Output

• GraphQL query cost tracking with per-operation metrics
• Rate limit monitoring for both REST and GraphQL
• Webhook delivery and processing metrics
• Structured logs with automatic PII redaction
• Alert rules for critical Shopify-specific conditions

Error Han…

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 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 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 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 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

Examples

Reducing Query Cost on a Product Sync

A product sync job hits THROTTLED errors. Analyze the cost…

Shopify Policy & Guardrails

Overview

Automated policy enforcement for Shopify apps: secret detection, query cost budgets, App Store compliance checks, and CI policy validation.

Prerequisites

• ESLint configured in project
• Pre-commit hooks infrastructure
• CI/CD pipeline with GitHub Actions
• Shopify app with shopify.app.toml

Instructions

Step 1: Secret Detection Rules

Custom ESLint rule that catches hardcoded Shopify tokens (shpat_*, shpss_*) and API secrets in string literals and template literals.

See Secret Detection ESLint for the complete rule implementation.

Step 2: Query Cost Budget Enforcement

Static analysis of GraphQL queries enforcing budgets: max 100 items per first: param, max 3 levels of nesting, and max 500 estimated cost. Runs at build/test time.

See Query Cost Budget for the complete implementation.

Step 3: Pre-Commit Hooks

Git hooks that scan staged changes for Shopify tokens and block .env files from being committed.

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: shopify-token-scan
        name: Scan for Shopify tokens
        language: system
        entry: bash -c '
          if git diff --cached --diff-filter=d | grep -E "shpat_[a-f0-9]{32}|shpss_[a-f0-9]{32}" ; then
            echo "ERROR: Shopify access token detected in staged changes"
            exit 1
          fi'
        pass_filenames: false

      - id: shopify-env-check
        name: Check .env not staged
        language: system
        entry: bash -c '
          if git diff --cached --name-only | grep -E "^\.env$|^\.env\.local$|^\.env\.production$" ; then
            echo "ERROR: .env file staged for commit"
            exit 1
          fi'
        pass_filenames: false

Step 4: App Store Compliance Checker

Pre-submission script that validates all three GDPR webhooks, token hygiene, CSP headers, and API version stability.

See Compliance Checker for the complete implementation.

Step 5: CI Policy Pipeline

GitHub Actions workflow enforcing token scanning, GDPR webhook configuration, and API version stability on every push and PR.

See CI Policy Pipeline for the complete workflow.

Output

• ESLint rules catching hardcoded tokens
• Query cost budgets enforced
• Pre-commit hooks blocking secret leaks
• App Store compliance checker
• CI policy pipeline preventing violations

Error Handling

Shopify Production Checklist

Overview

Complete pre-launch checklist for deploying Shopify apps to production and submitting to the Shopify App Store.

Prerequisites

• Staging environment tested and verified
• Shopify Partner account with app configured
• All development and staging tests passing

Instructions

Step 1: API and Authentication

• [ ] Using a recent stable API version (e.g., 2025-04), not unstable
• [ ] Access token stored in secure environment variables (never in code)
• [ ] API secret stored securely for webhook HMAC verification
• [ ] OAuth flow tested with a fresh install on a clean dev store
• [ ] Session persistence implemented (database or Redis, not in-memory)
• [ ] Token refresh/re-auth handled for expired sessions
• [ ] APP_UNINSTALLED webhook handler cleans up sessions

Step 2: Mandatory GDPR Compliance

• [ ] customers/data_request webhook handler implemented
• [ ] customers/redact webhook handler implemented
• [ ] shop/redact webhook handler implemented (fires 48h after uninstall)
• [ ] All three configured in shopify.app.toml
• [ ] Handlers respond with HTTP 200 within 5 seconds
• [ ] Customer data deletion actually works (test it!)

Step 3: Webhook Security

• [ ] All webhooks verify X-Shopify-Hmac-Sha256 using HMAC-SHA256
• [ ] Using crypto.timingSafeEqual() for signature comparison
• [ ] Webhook endpoints use raw body parsing (not JSON middleware)
• [ ] Idempotency: duplicate webhook deliveries handled gracefully

Step 4: Rate Limit Resilience

• [ ] GraphQL queries optimized (check requestedQueryCost with debug header)
• [ ] Retry logic with exponential backoff for 429 / THROTTLED responses
• [ ] Bulk operations used for large data exports instead of paginated queries
• [ ] No unbounded loops that could exhaust rate limits

Step 5: Error Handling

• [ ] All GraphQL mutations check userErrors array (200 with errors!)
• [ ] HTTP 4xx/5xx errors caught and logged with X-Request-Id
• [ ] Graceful degradation when Shopify is unavailable
• [ ] No PII logged (customer emails, addresses, phone numbers)

Step 6: App Store Submission Requirements

• [ ] App listing has clear name, description, and screenshots
• [ ] Privacy policy URL provided
• [ ] App has proper onboarding flow for new merchants
• [ ] Embedded app uses App Bridge for navigation (no full-page redirects)
• [ ] CSP headers set: frame-ancestors https://*.myshopify.com https://admin.shopify.com
• [ ] App works on both de…

Shopify Rate Limits

Overview

Shopify uses two distinct rate limiting systems: leaky bucket for REST and calculated query cost for GraphQL. This skill covers both with real header values and response shapes.

Prerequisites

• Understanding of Shopify's REST and GraphQL Admin APIs
• Familiarity with the @shopify/shopify-api library

Instructions

Step 1: Understand the Two Rate Limit Systems

REST Admin API -- Leaky Bucket:

The X-Shopify-Shop-Api-Call-Limit header shows your bucket state (e.g., 32/40 means 32 of 40 slots used). When full, you get HTTP 429 with Retry-After header.

GraphQL Admin API -- Calculated Query Cost:

Every GraphQL response includes cost info in extensions.cost with requestedQueryCost (worst-case estimate), actualQueryCost (real cost, often much lower), and throttleStatus (available points and restore rate). When currentlyAvailable drops to 0, you get THROTTLED.

Step 2: Implement GraphQL Cost-Aware Throttling

Client-side rate limiter that tracks the query cost bucket and pre-emptively waits before sending requests that would be throttled. Updates available points from each response's throttleStatus.

See Cost-Aware Rate Limiter for the complete ShopifyRateLimiter class.

Step 3: Implement Retry with Backoff for 429s

Generic retry wrapper handling both REST 429 responses and GraphQL THROTTLED errors. Uses Retry-After header when available, otherwise exponential backoff with jitter (max 30s).

See Retry with Backoff for the complete implementation.

Step 4: Reduce Query Cost

Prune unused fields and lower first: page sizes to reduce requestedQueryCost. A query dropping from first: 250 to first: 50 with fewer nested fields can go from ~5,500 to ~112 cost.

See Query Cost Reduction for before/after examples and the debug curl command.

Output

• Rate limit-aware client that prevents 429 errors
• Retry logic with proper b…

Shopify Reference Architecture

Overview

Production-ready architecture based on Shopify's official Remix app template. Covers project structure, session storage with Prisma, extension architecture, and the recommended app patterns.

Prerequisites

• Understanding of Remix framework basics
• Shopify CLI 3.x installed
• Familiarity with Prisma ORM

Instructions

Step 1: Official Project Structure (Remix Template)

my-shopify-app/
├── app/
│   ├── routes/
│   │   ├── app._index.tsx          # Main app dashboard
│   │   ├── app.products.tsx        # Product management page
│   │   ├── app.settings.tsx        # App settings
│   │   ├── auth.$.tsx              # OAuth catch-all route
│   │   ├── auth.login/
│   │   │   └── route.tsx           # Login page
│   │   └── webhooks.tsx            # Webhook handler
│   ├── shopify.server.ts           # Shopify API config (singleton)
│   ├── db.server.ts                # Database connection
│   └── root.tsx
├── extensions/
│   ├── theme-app-extension/        # Theme blocks for Online Store
│   ├── checkout-ui/                # Checkout UI extension
│   └── product-discount/           # Shopify Function
├── prisma/
│   ├── schema.prisma               # Database schema
│   └── migrations/
├── shopify.app.toml                # App configuration
├── shopify.web.toml                # Web process config
├── remix.config.js
└── package.json

Step 2: Core App Configuration

The shopify.server.ts singleton configures the API client, session storage, webhooks, and auth hooks. It uses LATEST_API_VERSION from @shopify/shopify-api and exports all auth/session helpers.

See Core App Configuration for the complete implementation.

Step 3: Session Storage with Prisma

The Prisma schema defines the required Session model (matching Shopify's session fields) plus your app's custom models. Use SQLite for dev and PostgreSQL for production.

See Prisma Session Storage for the complete schema.

Step 4: Route Pattern — Authenticated Admin Page

Each app route calls authenticate.admin(request) to get a pre-authenticated GraphQL client, then renders with Polaris components. Data flows through Remix loaders.

See Authenticated Admin Route for the complete implementation.

Step 5: Theme App Extension

Theme app extensions add customizable blocks to the Online Store. Each block defines a Liquid template with a {% schema %} JSON block for merchant-facing settings.

See Theme App Extension for the complete implementation.

Output

• Remix app with…

Shopify Reliability Patterns

Overview

Build fault-tolerant Shopify integrations that handle API outages, webhook retry storms, and rate limit exhaustion gracefully.

Prerequisites

• Understanding of circuit breaker pattern
• Queue infrastructure (BullMQ, SQS, etc.) for async processing
• Cache layer for fallback data

Instructions

Step 1: Circuit Breaker for Shopify API

Wrap all Shopify API calls in a circuit breaker (using opossum) that opens at 50% error rate, only counting 5xx and timeout errors. When open, serve cached data. The breaker auto-tests recovery after 30 seconds in half-open state.

See Circuit Breaker for the complete implementation.

Step 2: Webhook Idempotency

Shopify retries webhooks up to 19 times over 48 hours if your endpoint doesn't return 200. Your handler must be idempotent. Use Redis to track X-Shopify-Webhook-Id with a 7-day TTL. Always respond 200 within 5 seconds, then process asynchronously.

See Webhook Idempotency for the complete implementation.

Step 3: Graceful Degradation with Cached Fallback

Implement a three-tier fallback: try the live API first (caching the result), fall back to cached data, then fall back to an alternative data source (e.g., local DB). Track the data source so you can log degraded responses.

See Cached Fallback for the complete implementation.

Step 4: Webhook Processing Queue

Don't process webhooks inline — queue them with BullMQ for resilience. Verify HMAC first, respond 200 immediately, then enqueue with topic/shop/payload metadata. The worker processes jobs with exponential backoff (5 retries) and idempotency checks.

See Webhook Processing Queue for the complete implementation.

Step 5: Rate Limit-Aware Retry

Retry logic that respects Shopify's Retry-After header (REST 429) and GraphQL throttle status restore rate. Calculates optimal wait time from available points rather than blindly backing off.

See Rate Limit-Aware Retry for the complete implementation.

Output

• Circuit breaker preventing cascade failures during Shopify outages
• Idempotent webhook processing preventing duplicate operations
• Graceful degradation with cached fallback data
• Queue-based webhook processing for resilience
• Rate limit-aware retry logic

Error Handling

Shopify SDK Patterns

Overview

Production-ready patterns for the @shopify/shopify-api library: singleton clients, typed GraphQL operations, session management, cursor-based pagination, codegen-typed operations, bulk operations, and webhook registry patterns.

Prerequisites

• @shopify/shopify-api v9+ installed
• Familiarity with Shopify's GraphQL Admin API
• Understanding of async/await and TypeScript generics

Instructions

Step 1: Typed GraphQL Client Wrapper

Initialize a singleton shopifyApi instance with LATEST_API_VERSION, cache sessions per shop, and expose a typed shopifyQuery<T>() helper that wraps client.request().

See Typed GraphQL Client for the complete implementation.

Step 2: Error Handling with Shopify Error Types

Custom ShopifyServiceError class that distinguishes retryable errors (429, 5xx) from permanent ones. Includes handleShopifyError() for error translation and safeShopifyCall() that returns {data, error} tuples instead of throwing.

See Error Handling for the complete implementation.

Step 3: Cursor-Based Pagination

Async generator paginateShopify<T>() for Relay-style cursor pagination. Yields batches of nodes, automatically following pageInfo.endCursor until hasNextPage is false. Memory-efficient for large datasets.

See Cursor Pagination for the complete implementation.

Step 4: Multi-Tenant Client Factory

ShopifyClientFactory class for apps installed on multiple stores. Creates isolated GraphqlClient instances per merchant with session caching. Includes removeClient() for eviction on app uninstall.

See Multi-Tenant Factory for the complete implementation.

Step 5: Codegen-Typed Operations

Use @shopify/api-codegen-preset to generate TypeScript types from your GraphQL operations. This eliminates manual type definitions and catches schema changes at build time.

// codegen.ts — project root config
import { shopifyApiProject, ApiType } from "@shopify/api-codegen-preset";

export default {
  schema: "https://shopify.dev/admin-graphql-direct-proxy",
  documents: ["src/**/*.{ts,tsx}"],
  projects: {
    default: shopifyApiProject({
      apiType: ApiType.Admin,
      apiVersion: "2025-04", // Update quarterly
      outputDir: "./src/types",
    }),
  },
};

// src/operations/products.ts — typed query…

Shopify Security Basics

Overview

Security essentials for Shopify apps: credential management, webhook HMAC validation, request verification, and least-privilege access scopes.

Prerequisites

• Shopify Partner account with app credentials
• Understanding of HMAC-SHA256 signatures
• Access to Shopify app configuration

Instructions

Step 1: Secure Credential Storage

# .env — NEVER commit
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret_key
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# .gitignore — add immediately
.env
.env.local
.env.*.local
*.pem

Token format reference:

Step 2: Webhook HMAC Verification

Shopify signs every webhook with your app's API secret using HMAC-SHA256. The signature is in the X-Shopify-Hmac-Sha256 header. Use crypto.timingSafeEqual for comparison to prevent timing attacks. The middleware must use raw body parser (not JSON parser).

See Webhook HMAC Verification for the complete implementation.

Step 3: OAuth Request Verification

Verify that incoming OAuth requests from Shopify are authentic by checking the HMAC query parameter. The library handles this automatically, but the manual approach sorts params alphabetically, creates a query string, and compares HMAC hex digests.

See OAuth Request Verification for the complete implementation.

Step 4: Minimal Access Scopes

Only request the scopes your app actually needs:

# shopify.app.toml — start minimal, add as needed
[access_scopes]
sc…

Shopify Storefront & Headless Commerce

Overview

The Storefront API is Shopify's public-facing GraphQL API for customer experiences. Unlike the Admin API (server-side, privileged), it uses a public access token safe for client-side code. Paired with the Cart API, it powers headless storefronts, mobile apps, and custom buying experiences.

Prerequisites

• Shopify store with a Storefront API access token (Headless channel or custom app)
• For Hydrogen: Node.js 18+ and Shopify CLI 3.x+
• Storefront API scopes: unauthenticated_read_products, unauthenticated_read_collections

Instructions

Step 1: Storefront API Client Setup

import { createStorefrontApiClient } from "@shopify/storefront-api-client";

const client = createStorefrontApiClient({
  storeDomain: "my-store.myshopify.com",
  apiVersion: LATEST_API_VERSION,
  publicAccessToken: "your-storefront-public-token", // Safe in browser
});

Step 2: Cart Operations

const { data } = await client.request(CART_CREATE, {
  variables: {
    input: {
      lines: [{ merchandiseId: "gid://shopify/ProductVariant/123", quantity: 2 }],
      buyerIdentity: { email: "customer@example.com", countryCode: "US" },
    },
  },
});
// Redirect to data.cartCreate.cart.checkoutUrl to complete purchase

Full cart mutations (cartLinesAdd, cartLinesUpdate, cartLinesRemove, cartDiscountCodesUpdate) in cart-api.md.

Step 3: Query Products (Storefront Schema)

// Storefront API schema differs from Admin API — field names are NOT the same
const { data } = await client.request(`
  query { products(first: 10) { edges { node {
    id title handle availableForSale
    priceRange { minVariantPrice { amount currencyCode } }
    variants(first: 5) { edges { node {
      id title availableForSale
      price { amount currencyCode }  // MoneyV2 object, not a string
      selectedOptions { name value }
    }}}
  }}}}
`);

Step 4: Storefront vs Admin API Decision Guide

Detailed comparison in …

Shopify Theme Performance

Overview

59% of Shopify stores lazy-load their LCP image, adding 3-5 seconds to perceived load time. This skill covers the highest-impact theme optimizations: fixing LCP image loading, switching to the modern image_url filter, profiling Liquid render times, and optimizing font delivery.

Prerequisites

• Access to the Shopify theme editor or theme files via CLI (shopify theme dev)
• Theme using Online Store 2.0 architecture (sections + JSON templates)
• Google Chrome DevTools or Lighthouse for measurement

Instructions

Step 1: Fix LCP Image Loading

The LCP element is usually the hero banner image. Find it in your theme's hero section:

{% comment %} BAD: lazy-loading the LCP image costs 3-5s {% endcomment %}
{{ section.settings.hero_image | image_url: width: 1200 | image_tag: loading: 'lazy' }}

{% comment %} GOOD: eager load + fetchpriority for LCP {% endcomment %}
{{ section.settings.hero_image | image_url: width: 1200 | image_tag:
    loading: 'eager',
    fetchpriority: 'high',
    sizes: '100vw' }}

Add a preload hint in theme.liquid inside <head>:

{%- if template.name == 'index' -%}
  <link rel="preload"
        href="{{ section.settings.hero_image | image_url: width: 1200 }}"
        as="image"
        fetchpriority="high">
{%- endif -%}

Step 2: Use the image_url Filter

The modern image_url filter replaces the deprecated img_url. It supports responsive images via srcset:

{% assign image = product.featured_image %}

<img src="{{ image | image_url: width: 800 }}"
     srcset="{{ image | image_url: width: 400 }} 400w,
             {{ image | image_url: width: 600 }} 600w,
             {{ image | image_url: width: 800 }} 800w,
             {{ image | image_url: width: 1200 }} 1200w"
     sizes="(max-width: 749px) 100vw, 50vw"
     width="{{ image.width }}"
     height="{{ image.height }}"
     loading="lazy"
     alt="{{ image.alt | escape }}">

Always set explicit width and height attributes to prevent CLS (Cumulative Layout Shift).

Step 3: Liquid Profiler

Append ?profile=true to any storefront URL to activate the Liquid profiler. It renders a table at the bottom of the page showing render times per snippet.

See references/liquid-profiling.md for how to read the output and common slow patterns.

Step 4: Font Loading

Preload critical fonts and use font-display: swap to prevent invi…

Shopify Upgrade & Migration

Overview

Guide for upgrading Shopify API versions (quarterly releases) and migrating from the legacy REST Admin API to the GraphQL Admin API. REST was deprecated as a legacy API on October 1, 2024.

Prerequisites

• Current Shopify API version identified
• Git for version control
• Test suite available
• Access to Shopify release notes

Instructions

Step 1: Check Current Version and Available Versions

# Check what API version you're using in code
grep -r "apiVersion" src/ --include="*.ts" --include="*.js"
grep -r "api_version" . --include="*.toml"

# Check what versions the store supports
curl -s -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/api/versions.json" \
  | jq '.supported_versions[] | {handle, display_name, supported, latest}'

Shopify releases quarterly (e.g., 2025-01, 2025-04, 2025-07, 2025-10). Versions are supported for ~12 months after release.

Step 2: Review Breaking Changes

Key breaking changes by version:

Step 3: Migrate REST to GraphQL

Side-by-side comparison of REST vs GraphQL patterns, plus a mapping table for common endpoints (products, orders, customers, webhooks).

See REST to GraphQL Migration for the complete examples and mapping table.

Step 4: Update API Version in Config

// src/shopify.ts — use LATEST_API_VERSION instead of hardcoded dates
import { LATEST_API_VERSION } from "@shopify/shopify-api";

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  hostName: process.env.SHOPIFY_HOST_NAME!,
  apiVersion: LATEST_API_VERSION,
  // ...
});

# shopify.app.toml
[webhooks]
api_version = "2025-04"  # Update quarterly

Step 5: Handle the Produ…

Shopify Webhooks & Events

Overview

Register webhooks via GraphQL, handle events with HMAC verification, and implement the mandatory GDPR compliance webhooks required for Shopify App Store submission.

Prerequisites

• Shopify app with API credentials configured
• HTTPS endpoint accessible from the internet (use shopify app dev tunnel for local)
• API secret for HMAC webhook verification

Instructions

Step 1: Register Webhooks via GraphQL

Use the webhookSubscriptionCreate mutation with WebhookSubscriptionTopic and WebhookSubscriptionInput to register subscriptions for all critical event topics (orders, products, customers, inventory, app lifecycle).

See Webhook Registration for the complete implementation.

Step 2: Configure Mandatory GDPR Webhooks

Required for App Store submission. These are configured in shopify.app.toml, not via API:

# shopify.app.toml
[webhooks]
api_version = "2025-04"  # Update quarterly

  # MANDATORY: customers/data_request
  [[webhooks.subscriptions]]
  topics = ["customers/data_request"]
  uri = "/webhooks/gdpr/data-request"

  # MANDATORY: customers/redact
  [[webhooks.subscriptions]]
  topics = ["customers/redact"]
  uri = "/webhooks/gdpr/customers-redact"

  # MANDATORY: shop/redact
  [[webhooks.subscriptions]]
  topics = ["shop/redact"]
  uri = "/webhooks/gdpr/shop-redact"

Step 3: Implement GDPR Webhook Handlers

Three mandatory handlers: (1) customer data request -- collect and send all data for a customer, (2) customer redact -- delete customer personal data and specified orders, (3) shop redact -- delete ALL shop data 48 hours after uninstall.

See GDPR Webhook Handlers for the complete implementation.

Step 4: Event Handler Pattern

A typed webhook dispatcher maps topics to handler functions. Verifies HMAC first, responds 200 immediately, then processes asynchronously. Unknown topics are logged but not rejected.

See Event Handler Pattern for the complete implementation.

Step 5: List and Manage Existing Webhooks

// Query all webhook subscriptions
const LIST_WEBHOOKS = `{
  webhookSubscriptions(first: 50) {
    edges {
      node {
        id
        topic
        endpoint {
          ... on WebhookHttpEndpoint { callbackUrl }
        }
        format
        createdAt
      }
    }
  }
}`;

// Delete a webhook
const DELETE_WEBHOOK = `
  mutation webhookSubscriptionDelete($id: ID!) {
    webhookSubscriptionDelete(id: $id) {
      deletedWebhookSubscriptionId
      user…