shopify-developer

# Shopify Developer Use this skill as the coordination hub. Keep implementation details in `references/` files and load only the file(s) needed for the task. ## Authentication Use quarterly API versions in all endpoints, for example `2026-01`. Admin GraphQL endpoint: ```bash https://${SHOP}.myshopify.com/admin/api/${API_VERSION}/graphql.json ``` Admin API headers: ```bash X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN} Content-Type: application/json ``` Storefront GraphQL endpoint: ```bash https://${SHOP}.myshopify.com/api/${API_VERSION}/graphql.json ``` Storefront API headers: ```bash X-Shopify-Storefront-Access-Token: ${SHOPIFY_STOREFRONT_TOKEN} Content-Type: application/json ``` Source environment variables from `~/.agents/.env` before running commands. ## API Conventions - Prefer GraphQL over REST for new work. - Include API version in the URL; update quarterly. - Paginate with cursors (`first/after`) rather than page numbers. - Handle both top-level `errors` and mutation `userErrors`. - Budget GraphQL query cost and throttle based on available points. - Use bulk operations for large export/import workloads. - Prefer idempotent mutation patterns for retry-safe writes. ## Core Workflows Theme development pipeline: - Pull current theme state, iterate in local dev, push to draft first. - Validate theme editor behavior (sections, blocks, settings) before live publish. - Reference: `references/theme-architecture.md`, `references/liquid.md`. Product and metafield management: - Define metafield/metaobject schemas first, then write values through Admin API. - Access values in Liquid and Storefront API using type-safe patterns. - Reference: `references/admin-api.md`, `references/metafields-metaobjects.md`. Checkout customization: - Use Checkout UI Extensions and Shopify Functions; avoid legacy checkout patterns. - Separate UI concerns (extensions) from pricing/fulfillment logic (functions). - Reference: `references/checkout-extensibility.md`, `references/shopify-functions.md`. ## Reference Files | File | When to read | |---|---| | `references/admin-api.md` | Product/order/customer/inventory GraphQL workflows; bulk operations. Grep hint: `bulkOperation`. | | `references/storefront-api.md` | Headless storefront queries, cart operations, customer account flows, localization. Grep hint: `cart`. | | `references/metafields-metaobjects.md` | Metafield types, definitions, Liquid access, metaobject CRUD. Grep hint: `metafieldsSet`. | | `references/liquid.md` | Liquid objects, filters, tags, render patterns, metafield rendering, performance tuning. | | `references/theme-architecture.md` | OS 2.0 structure, section schema, templates, app blocks, CLI deployment flow. | | `references/checkout-extensibility.md` | Checkout UI extensions, web pixels, migration timelines, post-purchase extensions. | | `references/shopify-functions.md` | Function types, WASM constraints, implementation/testing, Scripts migration path. | | `references/webhooks-events.md` | Webhook topics, compliance webhooks, HMAC verification, retries/idempotency. | | `references/platform-limits.md` | API versioning, limits, deprecation timelines, plan-specific capabilities. | ## Gotchas 1. Use `.value` when rendering metafields in Liquid. 2. Use `metafieldsDelete` (plural), not singular deletion mutation names. 3. Do not rely on `checkout.liquid`; migrate to checkout extensibility. 4. Plan Scripts migration before June 30, 2026 sunset. 5. Treat REST Admin API as maintenance-only for new implementation. 6. Rotate to supported API versions before the 12-month support window ends. 7. Implement idempotency keys for retry-safe writes before April 1, 2026 enforcement. 8. Remove deprecated Storefront tax fields during API upgrades. 9. Do not hand-edit `config/settings_data.json`; use Theme Editor. 10. Keep Shopify Functions logic minimal to stay inside strict runtime limits.