Shopify Apps skill for Claude Code

A Shopify app is done when it installs cleanly on a dev store, every Admin call goes through GraphQL with a pinned API version, every webhook is HMAC-verified and answered within 5 seconds, the three compliance webhooks work, and uninstall leaves no orphaned access tokens.

Ground rules

• Use the GraphQL Admin API. The REST Admin API is legacy (since October 2024) and new public apps submitted from April 2025 must be GraphQL-only. Treat any REST call in an existing app as migration debt.
• Pin an API version (YYYY-MM, released quarterly, each supported about 12 months). Put it in one constant and in shopify.app.toml. Upgrade deliberately, not by drift.
• Never put the client secret or Admin access tokens in frontend code, git, or logs. Read them from env (SHOPIFY_API_KEY, SHOPIFY_API_SECRET) or the platform’s secret store.
• Request the minimum scopes. Every extra scope is a review question and a merchant trust cost; adding a scope later forces merchants to re-approve.
• Store offline sessions per shop in a durable DB (Prisma/Postgres/Redis session storage), never in memory.

Workflow

- [ ] 1. Identify app type and surface (embedded admin, extension-only, custom app)
- [ ] 2. Inspect existing config: shopify.app.toml, scopes, API version, session storage
- [ ] 3. Implement Admin API work in GraphQL with cost awareness
- [ ] 4. Declare and verify webhooks (incl. compliance topics)
- [ ] 5. Build UI: App Bridge + Polaris, or extensions
- [ ] 6. Test on a dev store with `shopify app dev`
- [ ] 7. Deploy config and extensions with `shopify app deploy`

1. Choose the surface

Need	Build
Merchant settings/dashboards inside admin	Embedded app (React Router template; older apps use the Remix template)
Storefront widget merchants place in themes	Theme app extension (app block or app embed)
Custom discount, shipping, payment, cart, or checkout validation logic	Shopify Function (Wasm; JS or Rust)
UI inside checkout / thank-you / order status	Checkout UI extension (checkout steps need Plus)
Action or block inside admin resource pages	Admin action / block extension
One merchant, no App Store	Custom app created from the Dev Dashboard / Partner Dashboard
Replacing Shopify Scripts or checkout.liquid	Functions + checkout UI extensions (Scripts are being retired; plan migration now)

2. Inspect before changing

shopify version
cat shopify.app.toml                     # client_id, scopes, webhooks api_version, URLs
grep -rn "apiVersion\|ApiVersion" app/   # pinned version in code
grep -rn "/admin/api/.*\.json" .         # REST calls still to migrate
shopify app env show                     # values the CLI injects locally

Scaffold new work with the CLI rather than by hand:

shopify app init                          # pick the current template
shopify app dev                           # tunnel + dev store install + hot reload
shopify app generate extension            # theme, checkout UI, function, admin extensions
shopify app deploy                        # pushes app config + extension versions
shopify app config link                   # bind local toml to an app in Partners

3. GraphQL Admin API

In the React Router/Remix templates, authenticate.admin(request) validates the session token and returns an Admin client:

// app/routes/app.products.tsx
import { authenticate } from "../shopify.server";

export async function loader({ request }) {
  const { admin } = await authenticate.admin(request);
  const res = await admin.graphql(
    `#graphql
    query Products($first: Int!, $after: String) {
      products(first: $first, after: $after, query: "status:active") {
        nodes { id title handle totalInventory }
        pageInfo { hasNextPage endCursor }
      }
    }`,
    { variables: { first: 50, after: null } },
  );
  const { data, errors } = await res.json();
  if (errors?.length) throw new Error(JSON.stringify(errors));
  return data.products;
}

Rules for the Admin API:

• IDs are GIDs: gid://shopify/Product/123. Do not strip them to integers internally; store the GID.
• Paginate with cursors (first/after, pageInfo.endCursor). Max page size is 250.
• Rate limiting is cost-based (leaky bucket, restore rate depends on the merchant’s plan). Read extensions.cost.throttleStatus (currentlyAvailable, restoreRate) and back off when a THROTTLED error arrives; do not retry immediately in a loop.
• Mutations return userErrors { field message } with HTTP 200. Always check userErrors, not just errors.
• Products use the current product model: create the product, then manage variants with productVariantsBulkCreate / productVariantsBulkUpdate, options with productOptionsCreate. Older single-call variant patterns are removed in recent versions.
• For more than a few thousand records, use bulk operations instead of paging:

mutation {
  bulkOperationRunQuery(query: """
    { products { edges { node { id title variants { edges { node { id sku } } } } } } }
  """) {
    bulkOperation { id status }
    userErrors { field message }
  }
}

Then subscribe to the bulk_operations/finish webhook (or poll currentBulkOperation) and download the JSONL from url. Child rows reference parents via __parentId. Bulk mutations use bulkOperationRunMutation with a staged upload of a JSONL file.

• Store app data on Shopify objects with metafields; use app-reserved namespaces ($app:...) so merchants and other apps cannot overwrite them. Define metafield and metaobject definitions in shopify.app.toml when the template supports it.

4. Webhooks

Declare subscriptions in config so they deploy with the app version:

# shopify.app.toml
[webhooks]
api_version = "2025-10"

  [[webhooks.subscriptions]]
  topics = ["app/uninstalled"]
  uri = "/webhooks/app/uninstalled"

  [[webhooks.subscriptions]]
  topics = ["orders/create", "products/update"]
  uri = "/webhooks/commerce"

  [[webhooks.subscriptions]]
  compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
  uri = "/webhooks/compliance"

Handler with the template helper (verifies HMAC, parses topic/shop/payload):

export async function action({ request }) {
  const { topic, shop, payload, webhookId } = await authenticate.webhook(request);
  // returns 401 automatically if the HMAC is invalid
  await enqueue({ topic, shop, payload, webhookId }); // do real work async
  return new Response(null, { status: 200 });
}

Without the helper, verify manually against the raw body:

import crypto from "node:crypto";

function verifyShopifyWebhook(rawBody: Buffer, hmacHeader: string | null): boolean {
  if (!hmacHeader) return false;
  const digest = crypto
    .createHmac("sha256", process.env.SHOPIFY_API_SECRET!)
    .update(rawBody)
    .digest("base64");
  const a = Buffer.from(digest);
  const b = Buffer.from(hmacHeader);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// header: X-Shopify-Hmac-Sha256; also read X-Shopify-Topic, X-Shopify-Shop-Domain,
// X-Shopify-Webhook-Id (dedupe key), X-Shopify-API-Version

Webhook rules:

• Verify on the raw bytes. A JSON body parser that re-serializes breaks the HMAC.
• Respond 200 within 5 seconds; push work to a queue. Shopify retries failed deliveries (multiple attempts over several hours) and removes subscriptions that keep failing.
• Delivery is at-least-once and unordered. Dedupe on X-Shopify-Webhook-Id; compare updated_at before overwriting newer state.
• app/uninstalled: delete the shop’s sessions/tokens. shop/redact arrives ~48 hours after uninstall: erase shop data. customers/redact and customers/data_request: act on them and log completion. Public apps fail review without these.
• Webhooks are not a reconciliation mechanism. Run a periodic sync job for critical data.

To test signature handling locally, run python3 scripts/verify_shopify_hmac.py --secret-env SHOPIFY_API_SECRET --body body.json --hmac <header> (also supports --query for OAuth callback and app proxy signatures).

5. UI

• Embedded apps load App Bridge from Shopify’s CDN with the shopify-api-key meta tag; the global shopify object provides toasts, modals, navigation, and shopify.idToken(). Do not bundle old @shopify/app-bridge v3 action patterns into new code.
• Embedded auth uses session tokens plus token exchange (Shopify-managed installation). Never rely on third-party cookies or redirect-based OAuth inside the iframe.
• Use Polaris (web components are the current direction; @shopify/polaris React exists in many apps) so the app passes “Built for Shopify” design expectations.
• Theme app extensions: ship CSS/JS in the extension assets/, keep blocks small, and never inject script tags into themes via the Asset API.

6. Shopify Functions

• Generate with shopify app generate extension and choose the function type.
• Input is defined by input.graphql; output must match the function API schema. Functions have strict instruction-count and size limits: keep logic data-driven via metafields rather than hardcoded tables.
• Test with shopify app function run against saved input JSON before deploying.

Gotchas

• shopify app dev updates URLs in the Partner config for the dev app; never point it at the production app’s config.
• Access scope changes only take effect after the merchant re-authorizes. Detect missing scopes and redirect, rather than failing silently.
• Shop domain inputs (?shop=) must match ^[a-zA-Z0-9][a-zA-Z0-9-]*\.myshopify\.com$ before use, or you open a redirect/SSRF hole.
• GraphQL query: search strings use Shopify search syntax and are eventually consistent; a just-created product may not appear in a filtered search for a few seconds.
• Money fields are strings with currency (MoneyV2); never parse them to floats for math.
• Billing: use appSubscriptionCreate (or managed pricing); test charges need test: true on dev stores. Merchants must approve via the returned confirmationUrl.

Verification

1. Install on a fresh dev store via shopify app dev; confirm the embedded page loads without auth loops.
2. shopify app webhook trigger (pick topic and address) and confirm a 200 plus the job runs; send a tampered body and confirm 401.
3. Uninstall and reinstall: sessions deleted on uninstall, fresh token on reinstall.
4. Grep for REST: grep -rn "/admin/api/.*\.json" . returns nothing in new code.
5. Log extensions.cost for the heaviest query and confirm it stays well under the single-query limit.

Output contract

When adding a feature, report:

**Surface:** embedded route /app/bundles + product metafield definition
**Scopes:** added write_products (merchants must re-approve)
**API version:** 2025-10 (pinned in shopify.app.toml and shopify.server.ts)
**Webhooks:** products/update -> /webhooks/commerce (HMAC verified, deduped on webhook id)
**Tested:** dev store install, webhook trigger, tampered-HMAC 401, uninstall cleanup
**Follow-ups:** migrate 3 remaining REST calls in app/lib/legacy.ts