Shopify Apps skill for Codex

Done well means: the app is configured as code in shopify.app.toml, talks to a pinned Admin GraphQL API version, checks userErrors on every mutation, respects query cost, verifies every webhook HMAC against the raw body, implements the three compliance webhooks, and never deploys or charges merchants without explicit confirmation.

Inspect first

- [ ] Read AGENTS.md, package.json and shopify.app.toml (client_id, scopes, webhooks, api_version)
- [ ] Note the template (React Router is current; older apps use Remix) and the session storage
- [ ] Check for REST Admin calls (/admin/api/<v>/*.json): new public apps must use GraphQL
- [ ] Find every webhook handler and confirm HMAC verification happens before parsing
- [ ] Confirm which store is the dev store; never point experiments at a live merchant store

Shopify CLI needs network and a Partner/Dev Dashboard login; in an offline Codex sandbox, prepare the changes and ask the user to run CLI commands.

CLI loop

shopify app init                       # scaffold (choose the React Router template)
shopify app dev                        # tunnel + dev store install + hot reload
shopify app generate extension         # Functions, checkout UI, theme app extension...
shopify app function run               # run a Function locally against input JSON
shopify app deploy                     # creates and releases an app version: confirm first

shopify app deploy pushes config and extensions to every store that has the app. Treat it as a production release: show the user the diff of shopify.app.toml and extensions and get a clear yes.

Configuration as code

client_id = "..."
name = "Stock Sync"
application_url = "https://app.example.com"
embedded = true

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

[webhooks]
api_version = "2025-10"

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

  [[webhooks.subscriptions]]
  topics = ["products/update"]
  uri = "/webhooks/products"

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

• Scopes are least privilege; every extra scope is shown to the merchant and reviewed in app review. Customer and order fields with personal data need protected customer data access approved in the dashboard, or fields come back null/denied.
• Managed installation: Shopify installs with the scopes in the TOML; embedded apps get a session token from App Bridge and exchange it for an access token (token exchange). The template’s authenticate.admin(request) does this.
• API versions are quarterly (YYYY-MM) and supported for about 12 months. Pin one version for both GraphQL calls and webhooks; upgrade deliberately each quarter after reading the changelog.

Admin GraphQL

// app/routes/app.products.tsx (React Router template)
import { authenticate } from "../shopify.server";

export async function loader({ request }: { request: 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 variants(first: 10) { nodes { id sku inventoryQuantity } } }
        pageInfo { hasNextPage endCursor }
      }
    }`,
    { variables: { first: 50, after: null } },
  );
  const { data } = await res.json();
  return data.products;
}

Mutations return HTTP 200 even when they fail. Always read userErrors:

const res = await admin.graphql(
  `#graphql
  mutation SetMeta($metafields: [MetafieldsSetInput!]!) {
    metafieldsSet(metafields: $metafields) {
      metafields { id key }
      userErrors { field message code }
    }
  }`,
  { variables: { metafields: [{ ownerId: productGid, namespace: "custom", key: "erp_id",
                                type: "single_line_text_field", value: "ERP-8812" }] } },
);
const { data } = await res.json();
if (data.metafieldsSet.userErrors.length) throw new Error(JSON.stringify(data.metafieldsSet.userErrors));

Need	Use
Create or fully sync a product with variants	productSet (declarative; good for ERP syncs)
Add or edit variants	productVariantsBulkCreate / productVariantsBulkUpdate
Set inventory	inventorySetQuantities (per location, with reason)
Custom data	Metafields (metafieldsSet, up to 25 per call) or metaobjects
Read thousands of records	bulkOperationRunQuery, then download the JSONL from url
Write thousands of records	bulkOperationRunMutation with a staged JSONL upload

Rate limits

GraphQL is cost-based: each query has a calculated cost and the shop’s bucket refills at a plan-dependent rate. Read extensions.cost.throttleStatus (currentlyAvailable, restoreRate) and sleep before the bucket empties. A single query cannot exceed 1,000 points; request smaller pages or fewer nested connections. On THROTTLED errors, wait (requested - available) / restoreRate seconds and retry.

IDs are global IDs (gid://shopify/Product/123). Money values are decimal strings with a currency; never parse them into floats for arithmetic.

Webhooks

import crypto from "node:crypto";

export function verifyShopifyHmac(rawBody: Buffer, hmacHeader: string, secret: string) {
  const digest = crypto.createHmac("sha256", secret).update(rawBody).digest("base64");
  const a = Buffer.from(digest), b = Buffer.from(hmacHeader ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

The template’s authenticate.webhook(request) verifies for you; custom servers must read the raw body before any JSON middleware. Rules:

• Respond 200 within about 5 seconds; enqueue work. Shopify retries failed deliveries with backoff and removes subscriptions that keep failing.
• Deduplicate by X-Shopify-Webhook-Id; ordering is not guaranteed, so compare updated_at before overwriting newer data.
• Payload shape follows the webhook api_version; changing it is a breaking change for handlers.
• Compliance topics are mandatory for public apps: answer data requests and actually delete data on customers/redact and shop/redact.
• app/uninstalled: delete sessions and stop jobs for that shop.

To debug a failing signature from a captured delivery, run python3 scripts/verify_webhook_hmac.py body.json <hmac-header> <secret-env-var-name>; it reports whether the raw bytes verify and common causes when they do not. Trigger test events with shopify app webhook trigger --topic products/update --address <url>.

Extensions

Goal	Extension	Note
Custom discounts, shipping/payment rules, cart validation	Shopify Functions (Rust or JS compiled to Wasm)	Run on Shopify, strict instruction and size limits; test with shopify app function run
UI in checkout or thank-you/order status pages	Checkout UI extension	Checkout steps beyond thank-you/order status require Plus
Storefront widgets	Theme app extension (app blocks, app embeds)	Replaces ScriptTag injection; merchants place blocks in the theme editor
Actions inside the admin	Admin UI extensions

Functions get only the data their input query requests; keep the query minimal to stay under limits.

Billing

Charges use appSubscriptionCreate or appPurchaseOneTimeCreate, returning a confirmationUrl the merchant must approve. Use test: true on dev stores. Changing plans or prices for live merchants needs explicit confirmation from the user.

Gotchas

• Inventory lives per location (InventoryLevel); inventoryQuantity on variants is a total.
• Product search query: syntax is eventually consistent; do not read-after-write through it.
• Online vs offline tokens: background jobs need offline tokens; online tokens expire with the user session.
• Embedded apps must not set cookies for auth in iframes; use session tokens.
• Ignoring app/scopes_update leaves stored scopes stale after a merchant approves new ones.

Verification

• shopify app dev on a dev store; exercise each route and mutation, confirm userErrors empty.
• Trigger each subscribed webhook topic; confirm 200, HMAC verified, idempotent on replay.
• Log throttleStatus during a bulk sync and confirm no THROTTLED errors at steady state.
• Before deploy, list scopes and webhook topics in the TOML and get the user’s approval.