Hosted e-commerce with two APIs: Admin (REST + GraphQL) for store management, Storefront (GraphQL) for headless customer experiences. The canonical 2nth skill codifies six human roles — owner, merchandiser, content, support, marketing, operations — and gives each one its own AI tool set.
Shopify is the hosted e-commerce platform most direct-to-consumer retailers end up on. Modern instances expose two distinct APIs for different audiences: the Admin API for everyone inside the store, and the Storefront API for the shoppers facing it. You use them differently, authenticate them differently, and almost never on the same Worker.
| API | Shape | Use when |
|---|---|---|
| Admin API | REST + GraphQL | Store management — products, orders, customers, inventory, reporting. Anything the human team touches in the admin UI. |
| Storefront API | GraphQL | Headless customer experiences — custom storefronts, mobile apps, kiosks. What the shopper sees. |
The 2nth model: one person + one AI. What makes this skill distinct from a generic Shopify SDK wrapper is the role model. The canonical skill defines six humans you're likely to find in a Shopify-backed business, and gives each one an AI partner with its own tool set — the human decides, the AI enables. This is the frame to keep in your head when you're deciding which tools to expose on an MCP server.
| Role | The human decides | The AI enables |
|---|---|---|
| Store Owner | Strategy, pricing, brand direction | Revenue dashboards, trend analysis, competitor monitoring |
| Merchandiser | Collection curation, product selection | Auto-tagging, SEO optimisation, inventory-aware recommendations |
| Content Creator | Brand voice, creative direction | Draft product descriptions, blog posts, alt text, meta tags |
| Customer Service | Escalations, refunds, relationship calls | Order lookup, FAQ answers, draft responses, sentiment analysis |
| Marketing Manager | Campaign strategy, budget allocation | Audience segmentation, A/B copy, performance reporting |
| Operations | Exception handling, carrier selection | Order routing, stock alerts, fulfillment tracking, fraud flags |
Don't try to replace Shopify's internals. Read product, order, inventory, and customer data, enrich it with AI, and write back approved changes as first-class Shopify mutations. The checkout, payment capture, and fulfilment state machine all stay where they are.
Shopify's auth is simple once you stop trying to OAuth-everything. For integrations, you generate a custom app, pick scopes, and get a token per API. For public-facing apps you need OAuth — but that's not what this skill covers.
# Admin API — add this header to every request X-Shopify-Access-Token: shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Storefront API — different token, different header X-Shopify-Storefront-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx # Admin API base URLs https://{store}.myshopify.com/admin/api/2024-10/{resource}.json # REST https://{store}.myshopify.com/admin/api/2024-10/graphql.json # GraphQL
// Cloudflare Worker — Shopify Admin API call const res = await fetch( `https://${env.SHOPIFY_STORE}.myshopify.com/admin/api/2024-10/products.json?limit=50&status=active`, { headers: { 'X-Shopify-Access-Token': env.SHOPIFY_ADMIN_TOKEN } } ); const { products } = await res.json();
The Admin token is a full "log in as the store" credential. Leaked tokens have been used to exfiltrate entire customer databases. Store tokens in wrangler secret, rotate quarterly, and never pass them to the browser. Storefront tokens are public-safe — that's what they're for.
Four patterns carry most real Shopify integrations: the Admin REST endpoints for the loop-y workloads, the Admin GraphQL for anything that joins resources, an MCP tool matrix per role, and webhooks for reactive flows.
Admin REST — the resources you'll touch most.
# Products GET /admin/api/2024-10/products.json?limit=50&status=active POST /admin/api/2024-10/products.json PUT /admin/api/2024-10/products/{id}.json # Orders GET /admin/api/2024-10/orders.json?status=open&limit=50 POST /admin/api/2024-10/orders/{id}/fulfillments.json # Customers GET /admin/api/2024-10/customers.json?limit=50 GET /admin/api/2024-10/customers/search.json?query=email:user@example.com # Inventory GET /admin/api/2024-10/inventory_levels.json?location_ids=1234 POST /admin/api/2024-10/inventory_levels/set.json
Admin GraphQL — when you need joins. REST makes you chain calls to get a product with its variants, SEO metadata, and tags. GraphQL gets it in one round trip. Cost-based rate limiting applies — check extensions.cost in responses to know what you just spent.
{
products(first: 10, query: "status:active") {
edges {
node {
id
title
variants(first: 5) {
edges {
node { price inventoryQuantity sku }
}
}
seo { title description }
tags
}
}
}
}
MCP tool matrix — one role, one tool set. Mapping the 2nth role model to actual MCP tools. The store owner gets dashboards; merchandising gets product-surface mutations; content gets SEO and description writes; support gets order and customer reads; marketing gets segments and performance; ops gets fulfilment and stock.
const ROLE_TOOLS = { owner: ['get_revenue_dashboard', 'get_top_products', 'get_customer_growth', 'get_inventory_value'], merchandiser:['list_products', 'update_product', 'manage_collection', 'get_seo_audit', 'auto_tag_products'], content: ['get_product', 'update_product_description', 'generate_alt_text', 'update_seo_metadata'], support: ['search_orders', 'get_order_status', 'search_customers', 'draft_response', 'create_return'], marketing: ['get_sales_report', 'get_customer_segments', 'generate_campaign_copy', 'get_channel_performance'], operations: ['list_unfulfilled_orders', 'get_inventory_levels', 'create_fulfillment', 'flag_fraud_risk'], };
Webhooks — the reactive layer. Shopify fires webhooks on every significant event. Subscribe the ones that matter, sign verify the payloads, and route to the right role's AI.
| Webhook | Use case |
|---|---|
orders/create | Alert operations, update dashboards |
orders/fulfilled | Notify customer service, update tracking |
products/update | Trigger SEO re-audit |
inventory_levels/update | Check reorder points |
customers/create | Welcome sequence, segment assignment |
refunds/create | Alert customer service, flag patterns |
Rate limits — plan-aware. REST is request-per-second, GraphQL is point-per-second. Point cost varies by query complexity — complex queries cost more.
| Plan | REST | GraphQL |
|---|---|---|
| Standard | 2 req/sec | 50 points/sec |
| Advanced / Plus | 4 req/sec | 100 points/sec |
| Shopify Plus | 20 req/sec | 1000 points/sec |
Six specific failure modes lifted from the canonical skill — the ones that actually cost time the first time they happen.
Pin to 2024-10 (or whatever the current stable is). Deprecated versions return errors — not warnings — after their sunset date. Shopify ships a new version each quarter.
REST uses Link headers (next/previous URLs). GraphQL uses cursor-based edges → node. Don't mix client libraries that assume one style.
Complex nested queries cost more points. Always check extensions.cost in the response to know what you just spent. A single bad query can stall all subsequent calls.
REST support for metafields is limited and inconsistent. Use GraphQL for any metafield work — reading, writing, or listing.
Don't paginate through 10k products with REST. Use the GraphQL Bulk Operations API — kick off a job, poll for completion, download the JSONL file. Much faster, much less rate-limit pressure.
Amounts in REST are strings like "299.00". GraphQL uses the MoneyV2 scalar with amount and currencyCode. Never trust float arithmetic on either — use a decimal library.
Shopify explicitly requires tech/cloudflare/workers in its frontmatter and improves the biz/erp sub-domain. The MCP role matrix connects it sideways to agent protocols.
improves biz/erp — the role-based AI pattern contributes back up to the shared ERP skill.Shopify's developer docs are good — and quarterly API versions mean the canonical truth moves. Always check the API version you're pinned to before copying code from anywhere.