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 desktop and m

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 backoff for both RES

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

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

// 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 with codegen output
im

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

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

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
});

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

// 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 }
    }}}
  }}}}
`);

{% 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' }}

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

{% 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 }}">

# 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}'

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

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

// 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
      userErrors { field mes

/plugin install shopify-pack@claude-code-plugins-plus

npm install -g @shopify/cli
shopify app init --template remix
cd my-shopify-app
shopify app dev

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

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

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  hostName: "localhost",
  apiVersion: LATEST_API_VERSION,
  isCustomStoreApp: true,
  adminApiAccessToken: process.env.SHOPIFY_ACCESS_TOKEN!,
});

const session = shopify.session.customAppSession("your-store.myshopify.com");
const client = new shopify.clients.Graphql({ session });

const response = await client.request(`{
  shop { name }
  products(first: 5) {
    edges { node { id title status } }
  }
}`);

console.log("Store:", response.data.shop.name);