Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Figure out what the user actually needs before diving in:
- Goal — building/debugging an API or webhook integration, choosing a plan, a checkout/conversion question, or a store-ops task?
- Surface — GraphQL Admin API, REST Admin API (legacy), Storefront API, webhooks, or the no-code admin?
- App type — custom app (token from admin) or public app (OAuth, Dev Dashboard)?
- Plan — Basic, Grow, Advanced, or Plus? (Some features — Checkout Extensibility, higher API limits, B2B — are Plus-gated.)
Skip-ahead rule: if the prompt already says what they need, go straight to Step 2.
Step 2 — Route or answer directly
If the question is really about a cross-platform strategy, hand off with the exact command:
| If the user wants… | Route to |
|---|---|
| Checkout conversion / order bumps / cart-abandonment tactics across carts | /sales-checkout {question} |
| Whether to use a Merchant of Record for global VAT/sales tax | /sales-merchant-of-record {question} |
| Digital-product pricing & launch strategy | /sales-digital-products {question} |
| Wiring Shopify into another tool via iPaaS | /sales-integration {question} |
| Post-purchase email / abandoned-cart sequences | /sales-email-marketing {question} |
Otherwise it's a Shopify-specific question — answer it here.
Step 3 — Shopify platform reference
Read references/platform-guide.md for the full reference — capabilities and what's API vs webhook vs UI-only, pricing/plan gates, data model with JSON shapes, and quick-start recipes. For raw endpoint/auth/rate-limit/webhook detail, read references/shopify-api-reference.md.
Answer using only the relevant section — don't dump the whole guide.
Step 4 — Actionable guidance
- Build on GraphQL. REST Admin API is legacy as of 2024-10-01; new public apps must be GraphQL-only since 2025-04-01, and new features ship GraphQL-first. Don't start a new integration on REST.
- Verify every webhook. Compute HMAC-SHA256 over the raw request body with your app's API secret, base64-encode, and timing-safe-compare to
X-Shopify-Hmac-Sha256. The three mandatory GDPR/compliance webhooks must pass this or app review fails. - Treat webhooks as hints, not source of truth. Delivery isn't guaranteed and ordering isn't either — reconcile against the API and order by
updated_at/X-Shopify-Triggered-At. - Budget GraphQL cost, not request count. Watch
extensions.cost.throttleStatus; back off onTHROTTLED; use bulk operations for large exports.
If you discover a gotcha or fix not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-06) — re-verify plan gates, fees, and the current API version against live docs.
- REST is legacy. As of 2026 the latest version is
2026-04; REST endpoints still work but are frozen. GraphQL only for anything new. - HMAC trap: must hash the raw, unparsed body. Frameworks that JSON-parse the body before you reach it (Express
body-parser, etc.) silently break verification — capture the raw buffer first. - Throttling is cost-based on GraphQL. A query can request up to 1,000 points; mutations cost 10 each; connections scale with
first/last. A 100-point/sec bucket (Basic) refills 50/sec at the standard rate. - Checkout is locked down.
checkout.liquidcustomization andadditional scriptsare deprecated — checkout UI changes now go through Checkout Extensibility, and fully customizable checkout is effectively Plus-tier. - Transaction fees apply on top of card rates when you use a third-party payment gateway instead of Shopify Payments (e.g. ~2% on Basic) — they vanish with Shopify Payments.
- API access scopes must be requested at install; a missing scope returns an access-denied error, not empty data.
Related skills
/sales-checkout— Checkout-conversion strategy across carts (order bumps, upsells, cart-abandonment recovery)./sales-merchant-of-record— Whether to use a MoR (Paddle, Lemon Squeezy) for global tax instead of self-managing./sales-digital-products— Pricing, packaging, and launch strategy for digital products./sales-do— Not sure which skill to use? The router matches any sales objective to the right skill. Install:npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Verifying a webhook signature (developer/automation)
User: "My Shopify webhook HMAC check keeps failing — Shopify's automated GDPR checks won't pass."
Approach: Confirm they're hashing the raw request body (not a re-serialized JSON object) with the app's API secret, HMAC-SHA256, base64-encoded, compared timing-safely to X-Shopify-Hmac-Sha256. Point them at the verify snippet in references/shopify-api-reference.md, and remind them the three mandatory compliance topics (customers/data_request, customers/redact, shop/redact) must each return 200 with a valid HMAC.
Example 2: Syncing orders into a warehouse (developer/automation)
User: "How do I pull every order into BigQuery without getting rate-limited?"
Approach: Use a orders/create + orders/updated webhook for incremental sync, and a GraphQL bulk operation for the historical backfill (no per-query cost limit). Show the bulkOperationRunQuery pattern from the guide, and reconcile with updated_at since webhook delivery isn't guaranteed.
Example 3: Picking a plan
User: "I'm on Basic and a third-party gateway is charging me extra — is Advanced or Plus worth it?" Approach: Explain the third-party transaction fee drops by tier (and disappears with Shopify Payments), Advanced raises staff seats and lowers card rates, and Plus unlocks fully customizable checkout + ~500% higher API limits + B2B. Map their actual order volume and gateway choice to the breakeven.
Troubleshooting
"Webhook HMAC verification fails / compliance checks won't pass"
The #1 cause is hashing a parsed/re-serialized body. Read the raw bytes before any JSON middleware, HMAC-SHA256 with the API secret, base64-encode, timing-safe compare to X-Shopify-Hmac-Sha256. Ensure the three mandatory GDPR topics are subscribed and each responds 200.
"Getting 429 / THROTTLED errors"
GraphQL throttles by calculated query cost, not request count. Inspect extensions.cost.throttleStatus.currentlyAvailable, request fewer fields, and implement exponential backoff with jitter. For large reads switch to bulk operations, which bypass the per-query cost cap. REST uses a leaky bucket (~2 req/sec, 40 burst) — read Retry-After.
"My REST integration broke / a feature is GraphQL-only"
REST Admin API is legacy since 2024-10-01 and newer features are GraphQL-exclusive. Migrate the affected calls to GraphQL (see Shopify's REST→GraphQL migration mapping); pin a recent version like 2026-04 and budget for the quarterly version cadence.