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: readorders, writeorders, readcustomers, writecustomers, readfulfillments, writefulfillments
• Familiarity with shopify-core-workflow-a (products)

Instructions

Step 1: Query Orders

const QUERY_ORDERS = `
  query orders($first: Int!, $query: String, $after: String) {
    orders(first: $first, query: $query, after: $after, sortKey: CREATED_AT, reverse: true) {
      edges {
        node {
          id
          name                    # "#1001"
          createdAt
          displayFinancialStatus  # PAID, PENDING, REFUNDED, etc.
          displayFulfillmentStatus # FULFILLED, UNFULFILLED, PARTIALLY_FULFILLED
          totalPriceSet {
            shopMoney { amount currencyCode }
          }
          customer {
            id
            displayName
            email
          }
          lineItems(first: 10) {
            edges {
              node {
                title
                quantity
                variant {
                  id
                  sku
                  price
                }
                originalTotalSet {
                  shopMoney { amount currencyCode }
                }
              }
            }
          }
          shippingAddress {
            address1
            city
            province
            country
            zip
          }
        }
        cursor
      }
      pageInfo { hasNextPage endCursor }
    }
  }
`;

// Shopify order query syntax:
// "financial_status:paid"
// "fulfillment_status:unfulfilled"
// "created_at:>2024-01-01"
// "name:#1001"
// "email:customer@example.com"
// "tag:rush"
const data = await client.request(QUERY_ORDERS, {
  variables: {
    first: 25,
    query: "financial_status:paid AND fulfillment_status:unfulfilled",
  },
});

Step 2: Create a Draft Order

const CREATE_DRAFT_ORDER = `
  mutation draftOrderCreate($input: DraftOrderInput!) {
    draftOrderCreate(input: $input) {
      draftOrder {
        id
        name
        totalPriceSet {
          shopMoney { amount currencyCode }
        }
        invoiceUrl
      }
      userErrors {
        field
        message
      }
    }
  }
`;

await client.request(CREATE_DRAFT_ORDER, {
  variables: {
    input: {
      lineItems: [
        {
          variantId: "gid://shopify/ProductVariant/12345",
          quantity: 2,
        },
        {
        

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 App Billing API:

// Create a recurring charge
const CREATE_SUBSCRIPTION = `
  mutation appSubscriptionCreate(
    $name: String!,
    $lineItems: [AppSubscriptionLineItemInput!]!,
    $returnUrl: URL!,
    $test: Boolean
  ) {
    appSubscriptionCreate(
      name: $name,
      lineItems: $lineItems,
      returnUrl: $returnUrl,
      test: $test
    ) {
      appSubscription {
        id
        status
      }
      confirmationUrl
      userErrors { field message }
    }
  }
`;

const response = await client.request(CREATE_SUBSCRIPTION, {
  variables: {
    name: "Pro Plan",
    returnUrl: "https://your-app.com/billing/callback",
    test: process.env.NODE_ENV !== "production", // test charges in dev
    lineItems: [
      {
        plan: {
          appRecurringPricingDetails: {
            price: { amount: 9.99, currencyCode: "USD" },
            interval: "EVERY_30_DAYS",
          },
        },
      },
    ],
  },
});

// Redirect merchant to confirmationUrl to approve the charge

Step 3: Monitor API Usage

class ShopifyUsageTracker {
  private graphqlCosts: number[] = [];
  private restCalls: number = 0;
  private startOfPeriod: Date = new Date();

  trackGraphqlCost(extensions: any): void {
    if (extensions?.cost?.actualQueryCost) {
      this.graphqlCosts.push(extensions.cost.actualQueryCost);
    }
  }

  trackRestCall(): void {
    this.restCalls++;
  }

  getReport(): UsageReport {
 

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.

// 1. customers/data_request — Customer requests their data
// Shopify sends this when a customer asks the merchant for their data
async function handleCustomerDataRequest(payload: {
  shop_domain: string;
  customer: { id: number; email: string; phone: string };
  orders_requested: number[];
  data_request: { id: number };
}): Promise<void> {
  // Collect all data you store about this customer
  const customerData = await db.customerRecords.findMany({
    where: {
      shopDomain: payload.shop_domain,
      shopifyCustomerId: String(payload.customer.id),
    },
  });

  const orderData = await db.orderRecords.findMany({
    where: {
      shopDomain: payload.shop_domain,
      shopifyOrderId: { in: payload.orders_requested.map(String) },
    },
  });

  // You have 30 days to respond
  // Email the data to the merchant (or make it available via your app)
  await sendDataExport({
    requestId: payload.data_request.id,
    shop: payload.shop_domain,
    customer: customerData,
    orders: orderData,
  });
}

// 2. customers/redact — Delete specific customer's data
async function handleCustomerRedact(payload: {
  shop_domain: string;
  customer: { id: number; email: string; phone: string };
  orders_to_redact: number[];
}): Promise<void> {
  // Delete ALL 

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 Debug Bundle Script

#!/bin/bash
# shopify-debug-bundle.sh
set -euo pipefail

STORE="${SHOPIFY_STORE:-your-store.myshopify.com}"
TOKEN="${SHOPIFY_ACCESS_TOKEN}"
VERSION="${SHOPIFY_API_VERSION:-2024-10}"
BUNDLE_DIR="shopify-debug-$(date +%Y%m%d-%H%M%S)"

mkdir -p "$BUNDLE_DIR"

echo "=== Shopify Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Store: $STORE" | tee -a "$BUNDLE_DIR/summary.txt"
echo "API Version: $VERSION" | tee -a "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" | tee -a "$BUNDLE_DIR/summary.txt"
echo "---" | tee -a "$BUNDLE_DIR/summary.txt"

Step 2: Collect API State

# Shop info and plan
echo "--- Shop Info ---" >> "$BUNDLE_DIR/summary.txt"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/api/$VERSION/shop.json" \
  | jq '{name: .shop.name, plan: .shop.plan_name, domain: .shop.domain, timezone: .shop.iana_timezone}' \
  >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "FAILED: shop.json" >> "$BUNDLE_DIR/summary.txt"

# Granted access scopes
echo "--- Access Scopes ---" >> "$BUNDLE_DIR/summary.txt"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/oauth/access_scopes.json" \
  | jq '.access_scopes[].handle' \
  >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "FAILED: scopes" >> "$BUNDLE_DIR/summary.txt"

# Supported API versions
echo "--- API Versions ---" >> "$BUNDLE_DIR/summary.txt"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  "https://$STORE/admin/api/versions.json" \
  | jq '.supported_versions[] | {handle, display_name, latest, supported}' \
  >> "$BUNDLE_DIR/summary.txt" 2>&1 || echo "FAILED: versions" >> "$BUNDLE_DIR/summary.txt"

Step 3: Test Rate Limit State

# GraphQL rate limit check — inspects cost headers
echo "--- Rate Limit State ---" >> "$BUNDLE_DIR/summary.txt"
curl -sf -H "X-Shopify-Access-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -

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
vercel env add SHOPIFY_API_KEY production
vercel env add SHOPIFY_API_SECRET production
vercel env add SHOPIFY_SCOPES production
vercel env add SHOPIFY_APP_URL production

# Deploy
vercel --prod

// vercel.json
{
  "framework": "remix",
  "env": {
    "SHOPIFY_API_KEY": "@shopify-api-key",
    "SHOPIFY_API_SECRET": "@shopify-api-secret"
  },
  "headers": [
    {
      "source": "/webhooks(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" }
      ]
    }
  ],
  "functions": {
    "app/**/*.ts": { "maxDuration": 25 }
  }
}

Update shopify.app.toml with your Vercel URL:

[auth]
redirect_urls = [
  "https://your-app.vercel.app/auth/callback"
]

application_url = "https://your-app.vercel.app"

Step 3: Fly.io Deployment

# fly.toml
app = "my-shopify-app"
primary_region = "iad"

[env]
  NODE_ENV = "production"
  SHOPIFY_API_VERSION = "2024-10"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 1

[checks]
  [checks.health]
    port = 3000
    type = "http"
    interval = "15s"
    timeout = "2s"
    path = "/health"

# Set secrets (never in fly.toml)
fly secrets set \
  SHOPIFY_API_KEY="your_key" \
  SHOPIFY_API_SECRET="your_secret" \
  SHOPIFY_ACCESS_TOKEN="shpat_xxx"

# Deploy
fly deploy

# Check health
fly status
curl https://my-shopify-app.fly.dev/health

Step 4: Google Cloud Run Deployment

# Dockerfile
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm

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

// Query staff members and their permissions via GraphQL
const STAFF_QUERY = `{
  staffMembers(first: 50) {
    edges {
      node {
        id
        email
        firstName
        lastName
        isShopOwner
        active
        locale
        permissions: accessScopes {
          handle
          description
        }
      }
    }
  }
}`;

// Staff permissions match app access scopes:
// "read_products", "write_products", "read_orders", etc.
// A staff member can only use app features matching their store permissions

Step 2: App-Level Role Mapping

Map Shopify staff permissions to your app's roles:

type AppRole = "admin" | "manager" | "viewer" | "fulfillment";

interface RoleMapping {
  role: AppRole;
  requiredScopes: string[];
  allowedActions: string[];
}

const ROLE_MAPPINGS: RoleMapping[] = [
  {
    role: "admin",
    requiredScopes: ["write_products", "write_orders", "write_customers"],
    allowedActions: ["*"],
  },
  {
    role: "manager",
    requiredScopes: ["write_products", "read_orders"],
    allowedActions: ["manage_products", "view_orders", "view_analytics"],
  },
  {
    role: "fulfillment",
    requiredScopes: ["read_orders", "write_fulfillments"],
    allowedActions: ["view_orders", "create_fulfillment", "update_tracking"],
  },
  {
    role: "viewer",
    requiredScopes: ["read_products"],
    allowedActions: ["view_products", "view_analytics"],
  },
];

function determineRole(staffScopes: string[]): AppRole {
  // Find the highest-privilege role the staff member qualifies for
  for (const mapping of ROLE_MAPPINGS) {
    if (mapping.requiredScopes.every((s) => staffScopes.includes(s))) {
      return mapping.role;
    }
  }
  return "viewer"; // fallback
}

function canPerformAction(role: AppRole, action: string): boolean {
  const mapping = ROLE_MAPPINGS.find((m) => m.role === role);
  if (!mapping) return false;
  return mapping.allowedActions.includes("*") || mapping.allowedActions.includes(action);
}

Step 3: Embedded App Permission Middleware

// In an embedded Shopi

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

// hello-shopify.ts
import "@shopify/shopify-api/adapters/node";
import { shopifyApi } from "@shopify/shopify-api";
import "dotenv/config";

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

async function main() {
  const session = shopify.session.customAppSession(
    process.env.SHOPIFY_STORE!
  );

  const client = new shopify.clients.Graphql({ session });

  // Query shop info
  const shopInfo = await client.request(`{
    shop {
      name
      currencyCode
      primaryDomain { url }
    }
  }`);
  console.log("Store:", shopInfo.data.shop.name);
  console.log("Currency:", shopInfo.data.shop.currencyCode);

  // Query first 5 products
  const products = await client.request(`{
    products(first: 5) {
      edges {
        node {
          id
          title
          status
          totalInventory
          variants(first: 3) {
            edges {
              node {
                title
                price
                sku
                inventoryQuantity
              }
            }
          }
        }
      }
    }
  }`);

  console.log("\nProducts:");
  for (const edge of products.data.products.edges) {
    const p = edge.node;
    console.log(`  - ${p.title} (${p.status}, ${p.totalInventory} in stock)`);
    for (const v of p.variants.edges) {
      console.log(`      Variant: ${v.node.title} — $${v.node.price} (SKU: ${v.node.sku})`);
    }
  }

  console.log("\nSuccess! Your Shopify connection is working.");
}

main().catch((err) => {
  console.error("Failed:", err.message);
  if (err.response) {
    console.error("Response:", JSON.stringify(err.response.body, null, 2));
  }
  process.exit(1);
});

Step

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
SHOPIFY_API_VERSION=2024-10

# .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, // or "2024-10"
  isEmbeddedApp: true,
});

export default shopify;

Step 4: Implement OAuth Flow (Public Apps)

// routes/auth.ts — Express example
import express from "express";
import shopify from "../shopify";

const router = express.Router();

// Step 1: Begin OAuth — redirect merchant to Shopify
router.get("/auth", async (req, res) => {
  const shop = req.query.shop as string;
  // Generates the authorization URL with HMAC validation
  const authRoute = await shopify.auth.begin({
    shop: shopify.utils.sanitizeShop(shop, true)!,
    callbackPath: "/auth/callback",
    isOnline: false, // offline = long-lived token
    rawRequest: req,
    rawResponse: res,
  });
});

// Step 2: Handle callback — exchange code for access tok

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

• Shopify app codebase to review
• Understanding of GraphQL Admin API patterns

Instructions

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

Shopify GraphQL mutations return HTTP 200 even when they fail. The errors are in userErrors.

// WRONG — assumes 200 means success
const response = await client.request(PRODUCT_CREATE, { variables });
const product = response.data.productCreate.product; // null!
console.log(product.title); // TypeError: Cannot read property 'title' of null

// RIGHT — always check userErrors
const response = await client.request(PRODUCT_CREATE, { variables });
const { product, userErrors } = response.data.productCreate;
if (userErrors.length > 0) {
  console.error("Shopify validation failed:", userErrors);
  // [{ field: ["title"], message: "Title can't be blank", code: "BLANK" }]
  throw new ShopifyValidationError(userErrors);
}
console.log(product.title); // Safe

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.

// WRONG — REST API (legacy, higher bandwidth, returns all fields)
const { body } = await restClient.get({ path: "products", query: { limit: 250 } });
// Returns EVERYTHING: body_html, template_suffix, published_scope...

// RIGHT — GraphQL (get only what you need)
const response = await graphqlClient.request(`{
  products(first: 50) {
    edges { node { id title status } }
    pageInfo { hasNextPage endCursor }
  }
}`);

Pitfall #3: Ignoring API Version Deprecation

Shopify deprecates API versions ~12 months after release. Your app will break silently when your version is removed.

// WRONG — hardcoded old version, no monitoring
const shopify = shopifyApi({ apiVersion: "2023-04" }); // DEAD version

// RIGHT — use recent stable version, monitor deprecation
const shopify = shopifyApi({ apiVersion: "2024-10" });

// Monitor for deprecation warnings in responses
function checkDeprecation(headers: Headers): void {
  const warning = headers.get("x-shopify-api-deprecated-reason");
  if (warning) {
    console.warn(`[DEPRECATION] ${warning}`);
    // Alert team to upgrade
  }
}

Pitfall #4: Missing Mandatory GDPR Webhooks

Your app will be rejected from the App Store without these three webhooks.

// WRONG — no GDPR handlers
// shopify.app.toml has no webhook subscriptions
// App Store review: REJECTED

// 

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

// shopify-load-test.js
import http from "k6/http";
import { check, sleep } from "k6";
import { Rate, Counter, Trend } from "k6/metrics";

// Custom metrics
const shopifyErrors = new Rate("shopify_errors");
const throttledRequests = new Counter("shopify_throttled");
const queryCost = new Trend("shopify_query_cost");

export const options = {
  stages: [
    { duration: "1m", target: 2 },    // Warm up — 2 VUs
    { duration: "3m", target: 5 },    // Normal load
    { duration: "2m", target: 10 },   // Peak load
    { duration: "1m", target: 0 },    // Ramp down
  ],
  thresholds: {
    http_req_duration: ["p(95)<2000"],  // 95% under 2s
    shopify_errors: ["rate<0.05"],      // < 5% error rate
    shopify_throttled: ["count<10"],    // < 10 throttled requests
  },
};

const STORE = __ENV.SHOPIFY_STORE;
const TOKEN = __ENV.SHOPIFY_ACCESS_TOKEN;
const API_VERSION = "2024-10";

export default function () {
  const query = JSON.stringify({
    query: `{
      products(first: 10) {
        edges {
          node { id title status totalInventory }
        }
      }
    }`,
  });

  const res = http.post(
    `https://${STORE}/admin/api/${API_VERSION}/graphql.json`,
    query,
    {
      headers: {
        "Content-Type": "application/json",
        "X-Shopify-Access-Token": TOKEN,
      },
    }
  );

  const body = JSON.parse(res.body);

  // Track GraphQL-level throttling (returns 200 with THROTTLED error)
  const isThrottled = body.errors?.some(
    (e) => e.extensions?.code === "THROTTLED"
  );

  if (isThrottled) {
    throttledRequests.add(1);
    // Wait for restore rate to refill
    const avai

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

# shopify.app.toml — central app configuration
name = "My App"
client_id = "your_api_key_here"

[access_scopes]
scopes = "read_products,write_products,read_orders"

[auth]
redirect_urls = [
  "https://localhost/auth/callback",
  "https://localhost/auth/shopify/callback",
]

[webhooks]
api_version = "2024-10"

  [webhooks.subscriptions]
  # Mandatory GDPR webhooks
  [[webhooks.subscriptions]]
  topics = ["customers/data_request"]
  uri = "/webhooks"

  [[webhooks.subscriptions]]
  topics = ["customers/redact"]
  uri = "/webhooks"

  [[webhooks.subscriptions]]
  topics = ["shop/redact"]
  uri = "/webhooks"

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

// tests/shopify-client.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";

// Mock the Shopify API client
vi.mock("@shopify/shopify-api", () => ({
  shopifyApi: vi.fn(() => ({
    clients: {
      Graphql: vi.fn().mockImplementation((

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: writeproducts, writecustomers, writeorders, writeinventory

Instructions

Step 1: Assess Migration Scope

Step 2: Bulk Product Import with productSet

productSet is idempotent — it creates or updates based on handle. Perfect for migrations.

const PRODUCT_SET = `
  mutation productSet($input: ProductSetInput!) {
    productSet(input: $input) {
      product {
        id
        title
        handle
        variants(first: 50) {
          edges {
            node { id sku price inventoryQuantity }
          }
        }
      }
      userErrors { field message code }
    }
  }
`;

// Migrate products in batches
async function migrateProducts(sourceProducts: SourceProduct[]): Promise<MigrationResult> {
  const results: MigrationResult = { success: 0, errors: [] };

  for (const product of sourceProducts) {
    try {
      const response = await client.request(PRODUCT_SET, {
        variables: {
          input: {
            title: product.name,
            handle: product.slug, // unique identifier for upsert
            descriptionHtml: product.description,
            vendor: product.brand,
            productType: product.category,
            tags: product.tags,
            status: "DRAFT", // Keep as draft until verified
            variants: product.variants.map((v) => ({
              price: String(v.price),
              sku: v.sku,
              barcode: v.barcode,
              optionValues: v.options.map((opt) => ({
                optionN

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 APIKEY, APISECRET, and ACCESS_TOKEN.

Step 2: Environment Configuration Files

# .env.development (git-ignored)
SHOPIFY_API_KEY=dev_api_key
SHOPIFY_API_SECRET=dev_api_secret
SHOPIFY_STORE=dev-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_dev_token
SHOPIFY_APP_URL=https://localhost:3000
SHOPIFY_API_VERSION=2024-10
NODE_ENV=development

# .env.staging (git-ignored)
SHOPIFY_API_KEY=staging_api_key
SHOPIFY_API_SECRET=staging_api_secret
SHOPIFY_STORE=staging-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_staging_token
SHOPIFY_APP_URL=https://staging.your-app.com
SHOPIFY_API_VERSION=2024-10
NODE_ENV=staging

# .env.production (never on disk — use secret manager)
# All values stored in Vault / AWS Secrets Manager / GCP Secret Manager

Step 3: Shopify CLI Configuration Per Environment

# shopify.app.dev.toml — development config
name = "My App (Dev)"
client_id = "dev_api_key"

[access_scopes]
scopes = "read_products,write_products,read_orders,write_orders"

[auth]
redirect_urls = ["https://localhost/auth/callback"]

[webhooks]
api_version = "2024-10"

# Switch between app configs
shopify app config use shopify.app.dev.toml
shopify app dev

shopify app config use shopify.app.toml  # production
shopify app deploy

Step 4: Environment-Aware Configuration

// src/config.ts
interface ShopifyEnvConfig {
  apiKey: string;
  apiSecret: string;
  appUrl: string;
  apiVersion: string;
  scopes: string[];
  environment: "development" | "staging" | "production";
  debug: boolean;
  sessionStorageType: "memory" | "sqlite" | "postgresql";
}

function getC

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

import { Registry, Counter, Histogram, Gauge } from "prom-client";

const registry = new Registry();

// GraphQL query cost tracking
const queryCostHistogram = new Histogram({
  name: "shopify_graphql_query_cost",
  help: "Shopify GraphQL actual query cost",
  labelNames: ["operation", "shop"],
  buckets: [1, 10, 50, 100, 250, 500, 1000],
  registers: [registry],
});

// Rate limit headroom
const rateLimitGauge = new Gauge({
  name: "shopify_rate_limit_available",
  help: "Shopify rate limit points currently available",
  labelNames: ["shop", "api_type"],
  registers: [registry],
});

// REST bucket state
const restBucketGauge = new Gauge({
  name: "shopify_rest_bucket_used",
  help: "REST API leaky bucket current fill level",
  labelNames: ["shop"],
  registers: [registry],
});

// API request duration
const apiDuration = new Histogram({
  name: "shopify_api_duration_seconds",
  help: "Shopify API call duration",
  labelNames: ["operation", "status", "api_type"],
  buckets: [0.1, 0.25, 0.5, 1, 2, 5, 10],
  registers: [registry],
});

// Webhook processing
const webhookCounter = new Counter({
  name: "shopify_webhooks_total",
  help: "Shopify webhooks received",
  labelNames: ["topic", "status"], // status: success, error, invalid_hmac
  registers: [registry],
});

// API errors by type
const apiErrors = new Counter({
  name: "shopify_api_errors_total",
  help: "Shopify API errors by type",
  labelNames: ["error_type", "status_code"],
  registers: [registry],
});

Step 2: Instrumented GraphQL Client

async function instrumentedGraphqlQuery<T>(
  shop: string,
  operation: string,
  query: string,
  variables?: Record<string, unknown>
): Promise<T> {
  const timer = apiDuration.startTimer({ operation, api_type: "graphql" });

  try {
    const client = getGraphqlClient(shop);
    const response = await client.request(query, { variables });

    // Record cost metrics from Shopify's response
    const cost = response.extensions?.cost;
    if (cost) {
      queryCostHistogram.observe(
        { operation, shop },
        cost.actualQueryCost || cost.requestedQueryCost
      );
      rateLimitGauge.set(
       

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

# Debug query cost with special header
curl -X POST "https://$STORE/admin/api/2024-10/graphql.json" \
  -H "X-Shopify-Access-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Shopify-GraphQL-Cost-Debug: 1" \
  -d '{"query": "{ products(first: 50) { edges { node { id title variants(first: 20) { edges { node { id price } } } } } } }"}' \
  | jq '.extensions.cost'

Response shows cost breakdown:

{
  "requestedQueryCost": 152,
  "actualQueryCost": 42,
  "throttleStatus": {
    "maximumAvailable": 1000.0,
    "currentlyAvailable": 958.0,
    "restoreRate": 50.0
  }
}

Key rule: requestedQueryCost is calculated as first * nested_fields. Reducing first: from 250 to 50 can cut cost by 5x.

Step 2: Reduce Query Cost

// BEFORE: High cost — requests too many fields and items
// requestedQueryCost: ~5,502
const EXPENSIVE_QUERY = `{
  products(first: 250) {
    edges {
      node {
        id title description descriptionHtml vendor productType tags
        variants(first: 100) {
          edges {
            node {
              id title price compareAtPrice sku barcode
              inventoryQuantity weight weightUnit
              selectedOptions { name value }
              metafields(first: 10) {
                edges { node { namespace key value type } }
              }
            }
          }
        }
        images(first: 20) {
          edges { node { url altText width height } }
        }
        metafields(first: 10) {
          edges { node { namespace key value type } }
        }
      }
    }
  }
}`;

// AFTER: Optimized — only needed fields, smaller page sizes
// requestedQueryCost: ~112
const OPTIMIZED_QUERY = `{
  products(first: 50) {
    edges {
      node {
        id
        title
        status
        variants(first: 5) {
          edges {
            node { id price sku inventoryQuantity }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}`;

Step 3: Use Bulk Operations for Large Exports

Bulk operations bypass rate limits and are designed for exporting large datasets:

                

                  
                    
                  
                  
                  shopify-policy-guardrails
                  SKILL.md
                  View full skill →
                
                

                  
Implement Shopify app policy enforcement with ESLint rules for API key detection, query cost budgets, and App Store compliance checks.
                  

                      ReadWriteEditBash(npx:*)
                    
                
                

                  
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

// eslint-rules/no-shopify-secrets.js
module.exports = {
  meta: {
    type: "problem",
    docs: { description: "Detect hardcoded Shopify tokens and secrets" },
    messages: {
      adminToken: "Hardcoded Shopify Admin API token detected (shpat_*)",
      apiSecret: "Potential Shopify API secret detected",
      storefrontToken: "Hardcoded Storefront API token detected",
    },
  },
  create(context) {
    return {
      Literal(node) {
        if (typeof node.value !== "string") return;
        const v = node.value;

        // Admin API access token: shpat_ + 32 hex chars
        if (/^shpat_[a-f0-9]{32}$/i.test(v)) {
          context.report({ node, messageId: "adminToken" });
        }
        // Storefront token: shpss_ pattern
        if (/^shpss_[a-f0-9]{32}$/i.test(v)) {
          context.report({ node, messageId: "storefrontToken" });
        }
        // Generic secret pattern (32+ hex that's clearly a token)
        if (/^[a-f0-9]{32,}$/i.test(v) && v.length === 32) {
          context.report({ node, messageId: "apiSecret" });
        }
      },
      TemplateLiteral(node) {
        for (const quasi of node.quasis) {
          if (/shpat_[a-f0-9]/i.test(quasi.value.raw)) {
            context.report({ node, messageId: "adminToken" });
          }
        }
      },
    };
  },
};

Step 2: Query Cost Budget Enforcement

// Enforce query cost budgets at build/test time
interface QueryCostBudget {
  maxFirstParam: number;        // Max items per page
  maxNestedDepth: number;       // Max nested connection depth
  maxEstimatedCost: number;     // Max estimated query cost
}

const BUDGET: QueryCostBudget = {
  maxFirstParam: 100,           // Never request more than 100 items
  maxNestedDepth: 3,            // No more than 3 levels of edges/node
  maxEstimatedCost: 500,        // Stay well under 1,000 point limit
};

function validateQueryCost(query: string): string[] {
  const violations: string[] = [];

  // Check `first:` parameter values
  const firstParams = query.matchAll(/first:\s*(\d+)/g);
  for (const match of firstParams) {
    if (parseInt(match[1]) > BUDGET.maxFirstParam) {
      violations.push(
        `first: ${match[1]} exceeds budget of ${BUDGET.maxFirstParam}`
      );
    }
  }

  // Check nesting depth (count "edges { node {" patterns)