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
errorsand mutationuserErrors. - •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
- •Use
.valuewhen rendering metafields in Liquid. - •Use
metafieldsDelete(plural), not singular deletion mutation names. - •Do not rely on
checkout.liquid; migrate to checkout extensibility. - •Plan Scripts migration before June 30, 2026 sunset.
- •Treat REST Admin API as maintenance-only for new implementation.
- •Rotate to supported API versions before the 12-month support window ends.
- •Implement idempotency keys for retry-safe writes before April 1, 2026 enforcement.
- •Remove deprecated Storefront tax fields during API upgrades.
- •Do not hand-edit
config/settings_data.json; use Theme Editor. - •Keep Shopify Functions logic minimal to stay inside strict runtime limits.