[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M737QT5QJARR7791QVT92F11":3,"skill-same:01M737QT5QJARR7791QVT92F11":80},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":59,"commitSha":60,"skillDirectory":61,"forksCount":62,"repositoryHtmlUrl":63,"repositoryHomepageUrl":6,"ownerHtmlUrl":64,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":65,"install":66,"resources":79},"01M737QT5QJARR7791QVT92F11","shopify",null,"Query Shopify Admin\u002FStorefront GraphQL APIs via curl.","ashneil12\u002Fvanilla-hermes-agent-canary","ashneil12","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F49880658?v=4","01M7378BQ9W161EPENEWBYAQNN","01M7378BRDJG8SFS93FG4V6BWY",1,"MIT","https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary\u002Fblob\u002Fmain\u002Foptional-skills\u002Fproductivity\u002Fshopify\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: shopify\ndescription: Query Shopify Admin\u002FStorefront GraphQL APIs via curl.\nversion: 1.0.0\nauthor: community\nlicense: MIT\nplatforms: [linux, macos, windows]\nprerequisites:\n  env_vars: [SHOPIFY_ACCESS_TOKEN, SHOPIFY_STORE_DOMAIN]\n  commands: [curl, jq]\nrequired_environment_variables:\n  - name: SHOPIFY_ACCESS_TOKEN\n    prompt: Shopify Admin API access token (starts with shpat_)\n    help: \"Shopify admin → Settings → Apps and sales channels → Develop apps → Create an app → API credentials. Token shown ONCE on install.\"\n  - name: SHOPIFY_STORE_DOMAIN\n    prompt: Your shop subdomain without protocol (e.g. my-store.myshopify.com)\n    help: \"The permanent myshopify.com domain, not your custom domain.\"\n  - name: SHOPIFY_API_VERSION\n    prompt: Shopify API version (default 2026-01)\n    help: \"Stable quarterly version. Override if you need an older one.\"\nmetadata:\n  hermes:\n    tags: [Shopify, E-commerce, Commerce, API, GraphQL]\n    related_skills: [airtable, xurl]\n    homepage: https:\u002F\u002Fshopify.dev\u002Fdocs\u002Fapi\u002Fadmin-graphql\n---\n\n# Shopify — Admin & Storefront GraphQL APIs\n\nWork with Shopify stores directly through `curl`: list products, manage inventory, pull orders, update customers, read metafields. No SDK, no app framework — just the GraphQL endpoint and a custom-app access token.\n\nThe REST Admin API is legacy since 2024-04 and only receives security fixes. **Use GraphQL Admin** for all admin work. Use **Storefront GraphQL** for read-only customer-facing queries (products, collections, cart).\n\n## Prerequisites\n\n1. In Shopify admin: **Settings → Apps and sales channels → Develop apps → Create an app**.\n2. Click **Configure Admin API scopes**, select what you need (examples below), save.\n3. **Install app** → the Admin API access token appears ONCE. Copy it immediately — Shopify will never show it again. Tokens start with `shpat_`.\n4. Save to `${HERMES_HOME:-~\u002F.hermes}\u002F.env`:\n   ```\n   SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxx\n   SHOPIFY_STORE_DOMAIN=my-store.myshopify.com\n   SHOPIFY_API_VERSION=2026-01\n   ```\n\n> **Heads up:** As of January 1, 2026, new \"legacy custom apps\" created in the Shopify admin are gone. New setups should use the **Dev Dashboard** (`shopify.dev\u002Fdocs\u002Fapps\u002Fbuild\u002Fdev-dashboard`). Existing admin-created apps keep working. If the user's shop has no existing custom app and it's after 2026-01-01, direct them to Dev Dashboard instead of the admin flow.\n\nCommon scopes by task:\n- Products \u002F collections: `read_products`, `write_products`\n- Inventory: `read_inventory`, `write_inventory`, `read_locations`\n- Orders: `read_orders`, `write_orders` (30 most recent without `read_all_orders`)\n- Customers: `read_customers`, `write_customers`\n- Draft orders: `read_draft_orders`, `write_draft_orders`\n- Fulfillments: `read_fulfillments`, `write_fulfillments`\n- Metafields \u002F metaobjects: covered by the matching resource scopes\n\n## API Basics\n\n- **Endpoint:** `https:\u002F\u002F$SHOPIFY_STORE_DOMAIN\u002Fadmin\u002Fapi\u002F$SHOPIFY_API_VERSION\u002Fgraphql.json`\n- **Auth header:** `X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN` (NOT `Authorization: Bearer`)\n- **Method:** always `POST`, always `Content-Type: application\u002Fjson`, body is `{\"query\": \"...\", \"variables\": {...}}`\n- **HTTP 200 does not mean success.** GraphQL returns errors in a top-level `errors` array and per-field `userErrors`. Always check both.\n- **IDs are GID strings:** `gid:\u002F\u002Fshopify\u002FProduct\u002F10079467700516`, `gid:\u002F\u002Fshopify\u002FVariant\u002F...`, `gid:\u002F\u002Fshopify\u002FOrder\u002F...`. Pass these verbatim — don't strip the prefix.\n- **Rate limit:** calculated via query cost (leaky bucket). Each response has `extensions.cost` with `requestedQueryCost`, `actualQueryCost`, `throttleStatus.{currentlyAvailable, maximumAvailable, restoreRate}`. Back off when `currentlyAvailable` drops below your next query's cost. Standard shops = 100 points bucket, 50\u002Fs restore; Plus = 1000\u002F100.\n\nBase curl pattern (reusable):\n\n```bash\nshop_gql() {\n  local query=\"$1\"\n  local variables=\"${2:-{}}\"\n  curl -sS -X POST \\\n    \"https:\u002F\u002F${SHOPIFY_STORE_DOMAIN}\u002Fadmin\u002Fapi\u002F${SHOPIFY_API_VERSION:-2026-01}\u002Fgraphql.json\" \\\n    -H \"Content-Type: application\u002Fjson\" \\\n    -H \"X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}\" \\\n    --data \"$(jq -nc --arg q \"$query\" --argjson v \"$variables\" '{query: $q, variables: $v}')\"\n}\n```\n\nPipe through `jq` for readable output. `-sS` keeps errors visible but hides the progress bar.\n\n## Discovery\n\n### Shop info + current API version\n```bash\nshop_gql '{ shop { name myshopifyDomain primaryDomain { url } currencyCode plan { displayName } } }' | jq\n```\n\n### List all supported API versions\n```bash\nshop_gql '{ publicApiVersions { handle supported } }' | jq '.data.publicApiVersions[] | select(.supported)'\n```\n\n## Products\n\n### Search products (first 20 matching query)\n```bash\nshop_gql '\nquery($q: String!) {\n  products(first: 20, query: $q) {\n    edges { node { id title handle status totalInventory variants(first: 5) { edges { node { id sku price inventoryQuantity } } } } }\n    pageInfo { hasNextPage endCursor }\n  }\n}' '{\"q\":\"hoodie status:active\"}' | jq\n```\n\nQuery syntax supports `title:`, `sku:`, `vendor:`, `product_type:`, `status:active`, `tag:`, `created_at:>2025-01-01`. Full grammar: https:\u002F\u002Fshopify.dev\u002Fdocs\u002Fapi\u002Fusage\u002Fsearch-syntax\n\n### Paginate products (cursor)\n```bash\nshop_gql '\nquery($cursor: String) {\n  products(first: 100, after: $cursor) {\n    edges { cursor node { id handle } }\n    pageInfo { hasNextPage endCursor }\n  }\n}' '{\"cursor\":null}'\n# subsequent calls: pass the previous endCursor\n```\n\n### Get a product with variants + metafields\n```bash\nshop_gql '\nquery($id: ID!) {\n  product(id: $id) {\n    id title handle descriptionHtml tags status\n    variants(first: 20) { edges { node { id sku price compareAtPrice inventoryQuantity selectedOptions { name value } } } }\n    metafields(first: 20) { edges { node { namespace key type value } } }\n  }\n}' '{\"id\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F10079467700516\"}' | jq\n```\n\n### Create a product with one variant\n```bash\nshop_gql '\nmutation($input: ProductCreateInput!) {\n  productCreate(product: $input) {\n    product { id handle }\n    userErrors { field message }\n  }\n}' '{\"input\":{\"title\":\"Test Hoodie\",\"status\":\"DRAFT\",\"vendor\":\"Hermes\",\"productType\":\"Apparel\",\"tags\":[\"test\"]}}'\n```\n\nVariants now have their own mutations in recent versions:\n\n```bash\n# Add variants after creating the product\nshop_gql '\nmutation($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {\n  productVariantsBulkCreate(productId: $productId, variants: $variants) {\n    productVariants { id sku price }\n    userErrors { field message }\n  }\n}' '{\"productId\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F...\",\"variants\":[{\"optionValues\":[{\"optionName\":\"Size\",\"name\":\"M\"}],\"price\":\"49.00\",\"inventoryItem\":{\"sku\":\"HD-M\",\"tracked\":true}}]}'\n```\n\n### Update price \u002F SKU\n```bash\nshop_gql '\nmutation($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {\n  productVariantsBulkUpdate(productId: $productId, variants: $variants) {\n    productVariants { id sku price }\n    userErrors { field message }\n  }\n}' '{\"productId\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F...\",\"variants\":[{\"id\":\"gid:\u002F\u002Fshopify\u002FProductVariant\u002F...\",\"price\":\"55.00\"}]}'\n```\n\n## Orders\n\n### List recent orders (last 30 by default without `read_all_orders`)\n```bash\nshop_gql '\n{\n  orders(first: 20, reverse: true, query: \"financial_status:paid\") {\n    edges { node {\n      id name createdAt displayFinancialStatus displayFulfillmentStatus\n      totalPriceSet { shopMoney { amount currencyCode } }\n      customer { id displayName email }\n      lineItems(first: 10) { edges { node { title quantity sku } } }\n    } }\n  }\n}' | jq\n```\n\nUseful order query filters: `financial_status:paid|pending|refunded`, `fulfillment_status:unfulfilled|fulfilled`, `created_at:>2025-01-01`, `tag:gift`, `email:foo@example.com`.\n\n### Fetch a single order with shipping address\n```bash\nshop_gql '\nquery($id: ID!) {\n  order(id: $id) {\n    id name email\n    shippingAddress { name address1 address2 city province country zip phone }\n    lineItems(first: 50) { edges { node { title quantity variant { sku } originalUnitPriceSet { shopMoney { amount currencyCode } } } } }\n    transactions { id kind status amountSet { shopMoney { amount currencyCode } } }\n  }\n}' '{\"id\":\"gid:\u002F\u002Fshopify\u002FOrder\u002F....\"}' | jq\n```\n\n## Customers\n\n```bash\n# Search\nshop_gql '\n{\n  customers(first: 10, query: \"email:*@example.com\") {\n    edges { node { id email displayName numberOfOrders amountSpent { amount currencyCode } } }\n  }\n}'\n\n# Create\nshop_gql '\nmutation($input: CustomerInput!) {\n  customerCreate(input: $input) {\n    customer { id email }\n    userErrors { field message }\n  }\n}' '{\"input\":{\"email\":\"test@example.com\",\"firstName\":\"Test\",\"lastName\":\"User\",\"tags\":[\"api-created\"]}}'\n```\n\n## Inventory\n\nInventory lives on **inventory items** tied to variants, quantities tracked per **location**.\n\n```bash\n# Get inventory for a variant across all locations\nshop_gql '\nquery($id: ID!) {\n  productVariant(id: $id) {\n    id sku\n    inventoryItem {\n      id tracked\n      inventoryLevels(first: 10) {\n        edges { node { location { id name } quantities(names: [\"available\",\"on_hand\",\"committed\"]) { name quantity } } }\n      }\n    }\n  }\n}' '{\"id\":\"gid:\u002F\u002Fshopify\u002FProductVariant\u002F...\"}'\n```\n\nAdjust stock (delta) — uses `inventoryAdjustQuantities`:\n\n```bash\nshop_gql '\nmutation($input: InventoryAdjustQuantitiesInput!) {\n  inventoryAdjustQuantities(input: $input) {\n    inventoryAdjustmentGroup { reason changes { name delta } }\n    userErrors { field message }\n  }\n}' '{\n  \"input\": {\n    \"reason\": \"correction\",\n    \"name\": \"available\",\n    \"changes\": [{\"delta\": 5, \"inventoryItemId\": \"gid:\u002F\u002Fshopify\u002FInventoryItem\u002F...\", \"locationId\": \"gid:\u002F\u002Fshopify\u002FLocation\u002F...\"}]\n  }\n}'\n```\n\nSet absolute stock (not delta) — `inventorySetQuantities`:\n\n```bash\nshop_gql '\nmutation($input: InventorySetQuantitiesInput!) {\n  inventorySetQuantities(input: $input) {\n    inventoryAdjustmentGroup { id }\n    userErrors { field message }\n  }\n}' '{\"input\":{\"reason\":\"correction\",\"name\":\"available\",\"ignoreCompareQuantity\":true,\"quantities\":[{\"inventoryItemId\":\"gid:\u002F\u002Fshopify\u002FInventoryItem\u002F...\",\"locationId\":\"gid:\u002F\u002Fshopify\u002FLocation\u002F...\",\"quantity\":100}]}}'\n```\n\n## Metafields & Metaobjects\n\nMetafields attach custom data to resources (products, customers, orders, shop).\n\n```bash\n# Read\nshop_gql '\nquery($id: ID!) {\n  product(id: $id) {\n    metafields(first: 10, namespace: \"custom\") {\n      edges { node { key type value } }\n    }\n  }\n}' '{\"id\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F...\"}'\n\n# Write (works for any owner type)\nshop_gql '\nmutation($metafields: [MetafieldsSetInput!]!) {\n  metafieldsSet(metafields: $metafields) {\n    metafields { id key namespace }\n    userErrors { field message code }\n  }\n}' '{\"metafields\":[{\"ownerId\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F...\",\"namespace\":\"custom\",\"key\":\"care_instructions\",\"type\":\"multi_line_text_field\",\"value\":\"Wash cold. Tumble dry low.\"}]}'\n```\n\n## Storefront API (public read-only)\n\nDifferent endpoint, different token, used for customer-facing apps\u002Fhydrogen-style headless setups. Headers differ:\n\n- **Endpoint:** `https:\u002F\u002F$SHOPIFY_STORE_DOMAIN\u002Fapi\u002F$SHOPIFY_API_VERSION\u002Fgraphql.json`\n- **Auth header (public):** `X-Shopify-Storefront-Access-Token: \u003Cpublic token>` — embeddable in browser\n- **Auth header (private):** `Shopify-Storefront-Private-Token: \u003Cprivate token>` — server-only\n\n```bash\ncurl -sS -X POST \\\n  \"https:\u002F\u002F${SHOPIFY_STORE_DOMAIN}\u002Fapi\u002F${SHOPIFY_API_VERSION:-2026-01}\u002Fgraphql.json\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"X-Shopify-Storefront-Access-Token: ${SHOPIFY_STOREFRONT_TOKEN}\" \\\n  -d '{\"query\":\"{ shop { name } products(first: 5) { edges { node { id title handle } } } }\"}' | jq\n```\n\n## Bulk Operations\n\nFor dumps larger than rate limits allow (full product catalog, all orders for a year):\n\n```bash\n# 1. Start bulk query\nshop_gql '\nmutation {\n  bulkOperationRunQuery(query: \"\"\"\n    { products { edges { node { id title handle variants { edges { node { sku price } } } } } } }\n  \"\"\") {\n    bulkOperation { id status }\n    userErrors { field message }\n  }\n}'\n\n# 2. Poll status\nshop_gql '{ currentBulkOperation { id status errorCode objectCount fileSize url partialDataUrl } }'\n\n# 3. When status=COMPLETED, download the JSONL file\ncurl -sS \"$URL\" > products.jsonl\n```\n\nEach JSONL line is a node, and nested connections are emitted as separate lines with `__parentId`. Reassemble client-side if needed.\n\n## Webhooks\n\nSubscribe to events so you don't have to poll:\n\n```bash\nshop_gql '\nmutation($topic: WebhookSubscriptionTopic!, $sub: WebhookSubscriptionInput!) {\n  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $sub) {\n    webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } } }\n    userErrors { field message }\n  }\n}' '{\"topic\":\"ORDERS_CREATE\",\"sub\":{\"callbackUrl\":\"https:\u002F\u002Fexample.com\u002Fwebhook\",\"format\":\"JSON\"}}'\n```\n\nVerify incoming webhook HMAC using the app's client secret (not the access token):\n\n```bash\necho -n \"$REQUEST_BODY\" | openssl dgst -sha256 -hmac \"$APP_SECRET\" -binary | base64\n# Compare to X-Shopify-Hmac-Sha256 header\n```\n\n## Pitfalls\n\n- **REST endpoints still exist but are frozen.** Don't write new integrations against `\u002Fadmin\u002Fapi\u002F...\u002Fproducts.json`. Use GraphQL.\n- **Token format check.** Admin tokens start with `shpat_`. Storefront public tokens with `shpua_`. If you have one and the wrong header, every request returns 401 without a useful error body.\n- **403 with a valid token = missing scope.** Shopify returns `{\"errors\":[{\"message\":\"Access denied for ...\"}]}`. Re-configure Admin API scopes on the app, then reinstall to regenerate the token.\n- **`userErrors` is empty != success.** Also check `data.\u003Cmutation>.\u003Cresource>` is non-null. Some failures populate neither — inspect the whole response.\n- **GID vs numeric ID.** Legacy REST gave numeric IDs; GraphQL wants full GID strings. To convert: `gid:\u002F\u002Fshopify\u002FProduct\u002F\u003Cnumeric>`.\n- **Rate limit surprise.** A single `products(first: 250)` with deep nesting can cost 1000+ points and throttle immediately on a standard-plan shop. Start narrow, read `extensions.cost`, adjust.\n- **Pagination order.** `products(first: N, reverse: true)` sorts by `id DESC`, not `created_at`. Use `sortKey: CREATED_AT, reverse: true` for \"newest first.\"\n- **`read_all_orders` for historical data.** Without it, `orders(...)` silently caps at the 60-day window. You won't get an error, just fewer results than expected. For Shopify Plus merchants with many orders, request this scope via the app's protected-data settings.\n- **Currencies are strings.** Amounts come back as `\"49.00\"` not `49.0`. Don't `jq tonumber` blindly if you care about zero-padding.\n- **Multi-currency Money fields** have `shopMoney` (store's currency) AND `presentmentMoney` (customer's). Pick one consistently.\n\n## Safety\n\nMutations in Shopify are real — they create products, charge refunds, cancel orders, ship fulfillments. Before running `productDelete`, `orderCancel`, `refundCreate`, or any bulk mutation: state clearly what the change is, on which shop, and confirm with the user. There is no staging clone of production data unless the user has a separate dev store.\n","# Shopify — Admin & Storefront GraphQL APIs\n\nWork with Shopify stores directly through `curl`: list products, manage inventory, pull orders, update customers, read metafields. No SDK, no app framework — just the GraphQL endpoint and a custom-app access token.\n\nThe REST Admin API is legacy since 2024-04 and only receives security fixes. **Use GraphQL Admin** for all admin work. Use **Storefront GraphQL** for read-only customer-facing queries (products, collections, cart).\n\n## Prerequisites\n\n1. In Shopify admin: **Settings → Apps and sales channels → Develop apps → Create an app**.\n2. Click **Configure Admin API scopes**, select what you need (examples below), save.\n3. **Install app** → the Admin API access token appears ONCE. Copy it immediately — Shopify will never show it again. Tokens start with `shpat_`.\n4. Save to `${HERMES_HOME:-~\u002F.hermes}\u002F.env`:\n   ```\n   SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxx\n   SHOPIFY_STORE_DOMAIN=my-store.myshopify.com\n   SHOPIFY_API_VERSION=2026-01\n   ```\n\n> **Heads up:** As of January 1, 2026, new \"legacy custom apps\" created in the Shopify admin are gone. New setups should use the **Dev Dashboard** (`shopify.dev\u002Fdocs\u002Fapps\u002Fbuild\u002Fdev-dashboard`). Existing admin-created apps keep working. If the user's shop has no existing custom app and it's after 2026-01-01, direct them to Dev Dashboard instead of the admin flow.\n\nCommon scopes by task:\n- Products \u002F collections: `read_products`, `write_products`\n- Inventory: `read_inventory`, `write_inventory`, `read_locations`\n- Orders: `read_orders`, `write_orders` (30 most recent without `read_all_orders`)\n- Customers: `read_customers`, `write_customers`\n- Draft orders: `read_draft_orders`, `write_draft_orders`\n- Fulfillments: `read_fulfillments`, `write_fulfillments`\n- Metafields \u002F metaobjects: covered by the matching resource scopes\n\n## API Basics\n\n- **Endpoint:** `https:\u002F\u002F$SHOPIFY_STORE_DOMAIN\u002Fadmin\u002Fapi\u002F$SHOPIFY_API_VERSION\u002Fgraphql.json`\n- **Auth header:** `X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN` (NOT `Authorization: Bearer`)\n- **Method:** always `POST`, always `Content-Type: application\u002Fjson`, body is `{\"query\": \"...\", \"variables\": {...}}`\n- **HTTP 200 does not mean success.** GraphQL returns errors in a top-level `errors` array and per-field `userErrors`. Always check both.\n- **IDs are GID strings:** `gid:\u002F\u002Fshopify\u002FProduct\u002F10079467700516`, `gid:\u002F\u002Fshopify\u002FVariant\u002F...`, `gid:\u002F\u002Fshopify\u002FOrder\u002F...`. Pass these verbatim — don't strip the prefix.\n- **Rate limit:** calculated via query cost (leaky bucket). Each response has `extensions.cost` with `requestedQueryCost`, `actualQueryCost`, `throttleStatus.{currentlyAvailable, maximumAvailable, restoreRate}`. Back off when `currentlyAvailable` drops below your next query's cost. Standard shops = 100 points bucket, 50\u002Fs restore; Plus = 1000\u002F100.\n\nBase curl pattern (reusable):\n\n```bash\nshop_gql() {\n  local query=\"$1\"\n  local variables=\"${2:-{}}\"\n  curl -sS -X POST \\\n    \"https:\u002F\u002F${SHOPIFY_STORE_DOMAIN}\u002Fadmin\u002Fapi\u002F${SHOPIFY_API_VERSION:-2026-01}\u002Fgraphql.json\" \\\n    -H \"Content-Type: application\u002Fjson\" \\\n    -H \"X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}\" \\\n    --data \"$(jq -nc --arg q \"$query\" --argjson v \"$variables\" '{query: $q, variables: $v}')\"\n}\n```\n\nPipe through `jq` for readable output. `-sS` keeps errors visible but hides the progress bar.\n\n## Discovery\n\n### Shop info + current API version\n```bash\nshop_gql '{ shop { name myshopifyDomain primaryDomain { url } currencyCode plan { displayName } } }' | jq\n```\n\n### List all supported API versions\n```bash\nshop_gql '{ publicApiVersions { handle supported } }' | jq '.data.publicApiVersions[] | select(.supported)'\n```\n\n## Products\n\n### Search products (first 20 matching query)\n```bash\nshop_gql '\nquery($q: String!) {\n  products(first: 20, query: $q) {\n    edges { node { id title handle status totalInventory variants(first: 5) { edges { node { id sku price inventoryQuantity } } } } }\n    pageInfo { hasNextPage endCursor }\n  }\n}' '{\"q\":\"hoodie status:active\"}' | jq\n```\n\nQuery syntax supports `title:`, `sku:`, `vendor:`, `product_type:`, `status:active`, `tag:`, `created_at:>2025-01-01`. Full grammar: https:\u002F\u002Fshopify.dev\u002Fdocs\u002Fapi\u002Fusage\u002Fsearch-syntax\n\n### Paginate products (cursor)\n```bash\nshop_gql '\nquery($cursor: String) {\n  products(first: 100, after: $cursor) {\n    edges { cursor node { id handle } }\n    pageInfo { hasNextPage endCursor }\n  }\n}' '{\"cursor\":null}'\n# subsequent calls: pass the previous endCursor\n```\n\n### Get a product with variants + metafields\n```bash\nshop_gql '\nquery($id: ID!) {\n  product(id: $id) {\n    id title handle descriptionHtml tags status\n    variants(first: 20) { edges { node { id sku price compareAtPrice inventoryQuantity selectedOptions { name value } } } }\n    metafields(first: 20) { edges { node { namespace key type value } } }\n  }\n}' '{\"id\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F10079467700516\"}' | jq\n```\n\n### Create a product with one variant\n```bash\nshop_gql '\nmutation($input: ProductCreateInput!) {\n  productCreate(product: $input) {\n    product { id handle }\n    userErrors { field message }\n  }\n}' '{\"input\":{\"title\":\"Test Hoodie\",\"status\":\"DRAFT\",\"vendor\":\"Hermes\",\"productType\":\"Apparel\",\"tags\":[\"test\"]}}'\n```\n\nVariants now have their own mutations in recent versions:\n\n```bash\n# Add variants after creating the product\nshop_gql '\nmutation($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {\n  productVariantsBulkCreate(productId: $productId, variants: $variants) {\n    productVariants { id sku price }\n    userErrors { field message }\n  }\n}' '{\"productId\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F...\",\"variants\":[{\"optionValues\":[{\"optionName\":\"Size\",\"name\":\"M\"}],\"price\":\"49.00\",\"inventoryItem\":{\"sku\":\"HD-M\",\"tracked\":true}}]}'\n```\n\n### Update price \u002F SKU\n```bash\nshop_gql '\nmutation($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {\n  productVariantsBulkUpdate(productId: $productId, variants: $variants) {\n    productVariants { id sku price }\n    userErrors { field message }\n  }\n}' '{\"productId\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F...\",\"variants\":[{\"id\":\"gid:\u002F\u002Fshopify\u002FProductVariant\u002F...\",\"price\":\"55.00\"}]}'\n```\n\n## Orders\n\n### List recent orders (last 30 by default without `read_all_orders`)\n```bash\nshop_gql '\n{\n  orders(first: 20, reverse: true, query: \"financial_status:paid\") {\n    edges { node {\n      id name createdAt displayFinancialStatus displayFulfillmentStatus\n      totalPriceSet { shopMoney { amount currencyCode } }\n      customer { id displayName email }\n      lineItems(first: 10) { edges { node { title quantity sku } } }\n    } }\n  }\n}' | jq\n```\n\nUseful order query filters: `financial_status:paid|pending|refunded`, `fulfillment_status:unfulfilled|fulfilled`, `created_at:>2025-01-01`, `tag:gift`, `email:foo@example.com`.\n\n### Fetch a single order with shipping address\n```bash\nshop_gql '\nquery($id: ID!) {\n  order(id: $id) {\n    id name email\n    shippingAddress { name address1 address2 city province country zip phone }\n    lineItems(first: 50) { edges { node { title quantity variant { sku } originalUnitPriceSet { shopMoney { amount currencyCode } } } } }\n    transactions { id kind status amountSet { shopMoney { amount currencyCode } } }\n  }\n}' '{\"id\":\"gid:\u002F\u002Fshopify\u002FOrder\u002F....\"}' | jq\n```\n\n## Customers\n\n```bash\n# Search\nshop_gql '\n{\n  customers(first: 10, query: \"email:*@example.com\") {\n    edges { node { id email displayName numberOfOrders amountSpent { amount currencyCode } } }\n  }\n}'\n\n# Create\nshop_gql '\nmutation($input: CustomerInput!) {\n  customerCreate(input: $input) {\n    customer { id email }\n    userErrors { field message }\n  }\n}' '{\"input\":{\"email\":\"test@example.com\",\"firstName\":\"Test\",\"lastName\":\"User\",\"tags\":[\"api-created\"]}}'\n```\n\n## Inventory\n\nInventory lives on **inventory items** tied to variants, quantities tracked per **location**.\n\n```bash\n# Get inventory for a variant across all locations\nshop_gql '\nquery($id: ID!) {\n  productVariant(id: $id) {\n    id sku\n    inventoryItem {\n      id tracked\n      inventoryLevels(first: 10) {\n        edges { node { location { id name } quantities(names: [\"available\",\"on_hand\",\"committed\"]) { name quantity } } }\n      }\n    }\n  }\n}' '{\"id\":\"gid:\u002F\u002Fshopify\u002FProductVariant\u002F...\"}'\n```\n\nAdjust stock (delta) — uses `inventoryAdjustQuantities`:\n\n```bash\nshop_gql '\nmutation($input: InventoryAdjustQuantitiesInput!) {\n  inventoryAdjustQuantities(input: $input) {\n    inventoryAdjustmentGroup { reason changes { name delta } }\n    userErrors { field message }\n  }\n}' '{\n  \"input\": {\n    \"reason\": \"correction\",\n    \"name\": \"available\",\n    \"changes\": [{\"delta\": 5, \"inventoryItemId\": \"gid:\u002F\u002Fshopify\u002FInventoryItem\u002F...\", \"locationId\": \"gid:\u002F\u002Fshopify\u002FLocation\u002F...\"}]\n  }\n}'\n```\n\nSet absolute stock (not delta) — `inventorySetQuantities`:\n\n```bash\nshop_gql '\nmutation($input: InventorySetQuantitiesInput!) {\n  inventorySetQuantities(input: $input) {\n    inventoryAdjustmentGroup { id }\n    userErrors { field message }\n  }\n}' '{\"input\":{\"reason\":\"correction\",\"name\":\"available\",\"ignoreCompareQuantity\":true,\"quantities\":[{\"inventoryItemId\":\"gid:\u002F\u002Fshopify\u002FInventoryItem\u002F...\",\"locationId\":\"gid:\u002F\u002Fshopify\u002FLocation\u002F...\",\"quantity\":100}]}}'\n```\n\n## Metafields & Metaobjects\n\nMetafields attach custom data to resources (products, customers, orders, shop).\n\n```bash\n# Read\nshop_gql '\nquery($id: ID!) {\n  product(id: $id) {\n    metafields(first: 10, namespace: \"custom\") {\n      edges { node { key type value } }\n    }\n  }\n}' '{\"id\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F...\"}'\n\n# Write (works for any owner type)\nshop_gql '\nmutation($metafields: [MetafieldsSetInput!]!) {\n  metafieldsSet(metafields: $metafields) {\n    metafields { id key namespace }\n    userErrors { field message code }\n  }\n}' '{\"metafields\":[{\"ownerId\":\"gid:\u002F\u002Fshopify\u002FProduct\u002F...\",\"namespace\":\"custom\",\"key\":\"care_instructions\",\"type\":\"multi_line_text_field\",\"value\":\"Wash cold. Tumble dry low.\"}]}'\n```\n\n## Storefront API (public read-only)\n\nDifferent endpoint, different token, used for customer-facing apps\u002Fhydrogen-style headless setups. Headers differ:\n\n- **Endpoint:** `https:\u002F\u002F$SHOPIFY_STORE_DOMAIN\u002Fapi\u002F$SHOPIFY_API_VERSION\u002Fgraphql.json`\n- **Auth header (public):** `X-Shopify-Storefront-Access-Token: \u003Cpublic token>` — embeddable in browser\n- **Auth header (private):** `Shopify-Storefront-Private-Token: \u003Cprivate token>` — server-only\n\n```bash\ncurl -sS -X POST \\\n  \"https:\u002F\u002F${SHOPIFY_STORE_DOMAIN}\u002Fapi\u002F${SHOPIFY_API_VERSION:-2026-01}\u002Fgraphql.json\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"X-Shopify-Storefront-Access-Token: ${SHOPIFY_STOREFRONT_TOKEN}\" \\\n  -d '{\"query\":\"{ shop { name } products(first: 5) { edges { node { id title handle } } } }\"}' | jq\n```\n\n## Bulk Operations\n\nFor dumps larger than rate limits allow (full product catalog, all orders for a year):\n\n```bash\n# 1. Start bulk query\nshop_gql '\nmutation {\n  bulkOperationRunQuery(query: \"\"\"\n    { products { edges { node { id title handle variants { edges { node { sku price } } } } } } }\n  \"\"\") {\n    bulkOperation { id status }\n    userErrors { field message }\n  }\n}'\n\n# 2. Poll status\nshop_gql '{ currentBulkOperation { id status errorCode objectCount fileSize url partialDataUrl } }'\n\n# 3. When status=COMPLETED, download the JSONL file\ncurl -sS \"$URL\" > products.jsonl\n```\n\nEach JSONL line is a node, and nested connections are emitted as separate lines with `__parentId`. Reassemble client-side if needed.\n\n## Webhooks\n\nSubscribe to events so you don't have to poll:\n\n```bash\nshop_gql '\nmutation($topic: WebhookSubscriptionTopic!, $sub: WebhookSubscriptionInput!) {\n  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $sub) {\n    webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } } }\n    userErrors { field message }\n  }\n}' '{\"topic\":\"ORDERS_CREATE\",\"sub\":{\"callbackUrl\":\"https:\u002F\u002Fexample.com\u002Fwebhook\",\"format\":\"JSON\"}}'\n```\n\nVerify incoming webhook HMAC using the app's client secret (not the access token):\n\n```bash\necho -n \"$REQUEST_BODY\" | openssl dgst -sha256 -hmac \"$APP_SECRET\" -binary | base64\n# Compare to X-Shopify-Hmac-Sha256 header\n```\n\n## Pitfalls\n\n- **REST endpoints still exist but are frozen.** Don't write new integrations against `\u002Fadmin\u002Fapi\u002F...\u002Fproducts.json`. Use GraphQL.\n- **Token format check.** Admin tokens start with `shpat_`. Storefront public tokens with `shpua_`. If you have one and the wrong header, every request returns 401 without a useful error body.\n- **403 with a valid token = missing scope.** Shopify returns `{\"errors\":[{\"message\":\"Access denied for ...\"}]}`. Re-configure Admin API scopes on the app, then reinstall to regenerate the token.\n- **`userErrors` is empty != success.** Also check `data.\u003Cmutation>.\u003Cresource>` is non-null. Some failures populate neither — inspect the whole response.\n- **GID vs numeric ID.** Legacy REST gave numeric IDs; GraphQL wants full GID strings. To convert: `gid:\u002F\u002Fshopify\u002FProduct\u002F\u003Cnumeric>`.\n- **Rate limit surprise.** A single `products(first: 250)` with deep nesting can cost 1000+ points and throttle immediately on a standard-plan shop. Start narrow, read `extensions.cost`, adjust.\n- **Pagination order.** `products(first: N, reverse: true)` sorts by `id DESC`, not `created_at`. Use `sortKey: CREATED_AT, reverse: true` for \"newest first.\"\n- **`read_all_orders` for historical data.** Without it, `orders(...)` silently caps at the 60-day window. You won't get an error, just fewer results than expected. For Shopify Plus merchants with many orders, request this scope via the app's protected-data settings.\n- **Currencies are strings.** Amounts come back as `\"49.00\"` not `49.0`. Don't `jq tonumber` blindly if you care about zero-padding.\n- **Multi-currency Money fields** have `shopMoney` (store's currency) AND `presentmentMoney` (customer's). Pick one consistently.\n\n## Safety\n\nMutations in Shopify are real — they create products, charge refunds, cancel orders, ship fulfillments. Before running `productDelete`, `orderCancel`, `refundCreate`, or any bulk mutation: state clearly what the change is, on which shop, and confirm with the user. There is no staging clone of production data unless the user has a separate dev store.\n",{"name":5,"author":23,"license":14,"version":24,"metadata":25,"platforms":37,"description":7,"prerequisites":41,"required_environment_variables":48},"community","1.0.0",{"hermes":26},{"tags":27,"homepage":33,"related_skills":34},[28,29,30,31,32],"Shopify","E-commerce","Commerce","API","GraphQL","https:\u002F\u002Fshopify.dev\u002Fdocs\u002Fapi\u002Fadmin-graphql",[35,36],"airtable","xurl",[38,39,40],"linux","macos","windows",{"commands":42,"env_vars":45},[43,44],"curl","jq",[46,47],"SHOPIFY_ACCESS_TOKEN","SHOPIFY_STORE_DOMAIN",[49,52,55],{"help":50,"name":46,"prompt":51},"Shopify admin → Settings → Apps and sales channels → Develop apps → Create an app → API credentials. Token shown ONCE on install.","Shopify Admin API access token (starts with shpat_)",{"help":53,"name":47,"prompt":54},"The permanent myshopify.com domain, not your custom domain.","Your shop subdomain without protocol (e.g. my-store.myshopify.com)",{"help":56,"name":57,"prompt":58},"Stable quarterly version. Override if you need an older one.","SHOPIFY_API_VERSION","Shopify API version (default 2026-01)","main","0905b0264ce5a54908bedc9637e50251543db132","optional-skills\u002Fproductivity\u002Fshopify",0,"https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary","https:\u002F\u002Fgithub.com\u002Fashneil12","2026-11-04 08:25:00",{"source":8,"skillName":5,"commands":67,"prompt":77,"zipAvailable":78},[68,71,74],{"tool":69,"command":70},"npx","npx skills add ashneil12\u002Fvanilla-hermes-agent-canary --skill shopify",{"tool":72,"command":73},"bunx","bunx skills add ashneil12\u002Fvanilla-hermes-agent-canary --skill shopify",{"tool":75,"command":76},"pnpm","pnpm dlx skills add ashneil12\u002Fvanilla-hermes-agent-canary --skill shopify","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary\u002Fblob\u002Fmain\u002Foptional-skills\u002Fproductivity\u002Fshopify\u002FSKILL.md",true,[],[81,88,95,102,109,116],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":18},"01M7380YR13A23353XT9NS6EGR","blocked-page-recovery","Use when a fetch fails: 403\u002F429, paywall, WAF, bot wall.","https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary\u002Fblob\u002Fmain\u002Fskills\u002Fweb\u002Fblocked-page-recovery\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":18},"01M7380VZ8P60Q64J3F92D4AMY","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":18},"01M7380QXN6F90R0MH1M3FHRKX","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":18},"01M7380N4BZYT2WRRZN1N9DZ65","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[],[],{"skillNo":110,"name":111,"nameZh":6,"description":112,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":18},"01M7380JAEC9ZH5DVPHHK56P97","simplify-code","Parallel 4-agent cleanup of recent code changes.","https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Fsimplify-code\u002FSKILL.md",[],[],{"skillNo":117,"name":118,"nameZh":6,"description":119,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":120,"categories":121,"keywords":122,"publishedAt":18},"01M7380F5MBB7FKWWV3G3TZ193","requesting-code-review","Pre-commit review: security scan, quality gates, auto-fix.","https:\u002F\u002Fgithub.com\u002Fashneil12\u002Fvanilla-hermes-agent-canary\u002Fblob\u002Fmain\u002Fskills\u002Fsoftware-development\u002Frequesting-code-review\u002FSKILL.md",[],[]]