# Shopify Admin API operator Produces safe, reviewable reads and writes on one Shopify store through the GraphQL Admin API: a change plan with before/after values for the owner to approve, then an execution log that doubles as a rollback file. The naive approach (grab a token, loop REST calls, treat HTTP 200 as success) fails three ways: GraphQL answers `200 OK` even when the operation failed, throttling arrives as a `THROTTLED` error in the body rather than HTTP 429, and a "convenient" mutation like `productSet` deletes every variant you left out of the input. **The key insight: on this API, success is never the status code. It is an empty `errors` array, an empty `userErrors` list, and a re-read that shows the new value.** ## When to use - The owner asks the agent to look something up in the store: a product by SKU, stock at a location, orders with a tag, a customer's order history, active discounts. - The owner wants a batch change: prices, compare-at prices, tags, order notes, metafields, collection membership, inventory corrections. - A large export (whole catalog, a year of orders) is needed as a file for another analysis. ## When not to use - Deciding what a price should be: `competitor-price-brief`, `promotion-profit-check`, `clearance-markdown-planner` (Omnibus prior price), `free-shipping-threshold-planner`. This skill only executes a decided change. - Marketplace channel economics: `marketplace-profitability-check`; feed quality: `product-feed-optimizer`, `merchant-center-disapproval-fixer`, `gtin-identifier-auditor`. - Replying to customers about orders: `order-status-reply-drafter`, `warranty-claim-handler`. - Reconciling Shopify revenue with GA4 or Ads: `revenue-discrepancy-reconciler`. - Rewriting product copy: `product-description-writer` (then use this skill to write the approved text back). ## Inputs | input | definition | typical source | |---|---|---| | Shop domain | `{shop}.myshopify.com`, not the storefront domain | Shopify admin URL | | API version | a supported quarterly version to pin, e.g. `2026-10` | owner or integration config | | Access token | Admin API token, read from an environment variable or secret store at run time | legacy custom app token, or client credentials grant for a Dev Dashboard app | | Granted scopes | the scopes the token actually holds | the `scope` field returned with the token, or the app's configuration | | Plan | Standard, Advanced, Plus or Enterprise, which sets the restore rate | Shopify admin, Settings > Plan | | The task | what to read or change, on which records, with the target values | the owner | Optional: location IDs for inventory, a preferred batch size, an owner-approved change window, the store currency and time zone. Missing input → stop and ask. Never guess a shop domain, an API version or a target value, and never fall back to "typical" store settings. ## Best practices ### Access and authentication 1. **GraphQL only.** The REST Admin API is legacy as of 2024-10-01, and since 2025-04-01 new public apps must be built exclusively with the GraphQL Admin API. New fields land in GraphQL; REST answers drift out of date. 2. **One endpoint, one header.** `POST https://{shop}.myshopify.com/admin/api/{version}/graphql.json` with the token in `X-Shopify-Access-Token`. Pin the version in the URL: versions ship quarterly (1 Jan, Apr, Jul, Oct, 17:00 UTC), each stable version is supported at least 12 months, and a request to an inaccessible version silently falls forward to the oldest accessible one, so field behaviour can change under you. 3. **Know which token the store has.** Custom apps can no longer be created in the Shopify admin after 2026-01-01; those created earlier ("legacy custom apps") keep working and are managed there. New custom apps are created in the Dev Dashboard; when app and store are in the same organization the app exchanges client ID and secret at `/admin/oauth/access_token` (`grant_type=client_credentials`) for a token that expires after 24 hours (`expires_in` 86399). Cache it and refresh before expiry. 4. **Secrets never leave the secret store.** Read the token and client secret from environment variables or a secret manager. Never write them into files, logs, change plans, commits or chat; log the variable name only. A token that appears in output is compromised and must be rotated by the owner. 5. **Least privilege, per task.** Request only what the task needs: `read_products`/`write_products` (products, variants, collections), `read_inventory`/`write_inventory`, `read_orders`/`write_orders` (orders of the last 60 days), `read_customers`, `read_discounts`/`write_discounts`. Do not ask for `read_all_orders` (needs Shopify approval) unless the task really needs orders older than 60 days. Each mutation's reference page lists its scope; check it before asking the owner to grant one. 6. **Customer data is protected data.** Name, email, phone and address are Level 2 protected customer data; Shopify requires data minimisation, stated purpose, retention limits and encryption. For admin-created custom apps Level 2 access depends on the store's plan. Read only the customer fields the task needs. ### Reading efficiently 7. **Page with cursors.** Use `first` (max 250) and `after: endCursor` until `pageInfo.hasNextPage` is false. Pagination stops at 25,000 objects, so bigger sets go to bulk. 8. **Filter on the server.** Use the `query` argument: `sku:LS-01-M`, `updated_at:>'2026-09-01T00:00:00Z'`, `-tag:archive`, `tag:wholesale OR tag:b2b`, quoted phrases, `field:*` for "has a value". Fetching everything and filtering locally burns cost points. 9. **Bulk for big exports.** `bulkOperationRunQuery` returns JSONL with `__parentId` for nested rows; max five connections, two levels deep; must finish within 10 days; the result URL expires after a week. From `2026-01` an app can run up to five bulk queries per shop at once (earlier versions: one of each type) and polls `bulkOperation(id:)`; `currentBulkOperation` is deprecated. 10. **Bulk imports only after a pilot.** `bulkOperationRunMutation` takes a JSONL variables file (max 100 MB) uploaded via `stagedUploadsCreate` with `BULK_MUTATION_VARIABLES`, must finish within 24 hours, and reports errors per line in the result file. Run the same mutation on 3 to 5 records first and verify them. ### Rate limits 11. **Budget by cost, not by request count.** Objects cost 1, connections are sized by `first`/`last`, mutations cost 10, one query may not exceed 1,000 points. Restore rates: Standard 100, Advanced 200, Plus 1,000, Enterprise 2,000 points/second. Shopify does not publish bucket sizes on that page, so read `extensions.cost.throttleStatus` (`maximumAvailable`, `currentlyAvailable`, `restoreRate`) from each response and pace from that. 12. **Back off on THROTTLED.** Wait (requested cost − currently available) ÷ restore rate seconds, plus jitter, then retry the same request. Never retry a write without first checking it did not land. ### Webhooks, briefly 13. **Polling is the default; webhooks only if a receiver exists.** If the owner already runs one, verify each delivery: HMAC-SHA256 of the raw body with the app's client secret, base64, compared timing-safe with `X-Shopify-Hmac-SHA256`; reply `200` within 5 seconds. Unverified payloads are discarded. ### Writing 14. **Check three things after every mutation:** top-level `errors`, the mutation's `userErrors`, and the returned object. HTTP 200 with a non-empty `userErrors` is a failed write. 15. **Use global IDs from reads.** IDs look like `gid://shopify/ProductVariant/123`; copy them from the read, never build them from storefront URLs or SKUs. 16. **Pick the narrowest mutation.** Prices and compare-at prices: `productVariantsBulkUpdate` (one product per call, `allowPartialUpdates` default false). Product fields: `productUpdate`. `productSet` replaces list fields: variants, collections and metafields missing from the input are deleted, so use it only for full syncs the owner approved. 17. **Inventory through quantities, with a reason.** `inventorySetQuantities` (absolute, `available` or `on_hand`) or `inventoryAdjustQuantities` (delta), with a `reason` such as `correction` or `cycle_count_available`, a `referenceDocumentUri` (GID format preferred) and `changeFromQuantity` so a stale read fails with `CHANGE_FROM_QUANTITY_STALE` instead of overwriting a sale. From `2026-04` these mutations require `@idempotent(key: ...)`; reuse the key on retry so a timeout does not apply the change twice. 18. **Tags and notes.** `tagsAdd` appends tags to an order, product, customer or discount; `orderUpdate` with `tags` replaces all existing tags. Notes via `orderUpdate` overwrite the old note, so log the old text. 19. **Metafields atomically.** `metafieldsSet` takes up to 25 per call, is all-or-nothing, and accepts `compareDigest` to refuse a write if someone changed the value since the read. ## Process 1. **Confirm setup**: shop domain, pinned version, token present in the environment (check presence, never print it), granted scopes cover the task. 2. **Read**: query the target records with only the needed fields; save IDs and current values. 3. **Plan**: build the change plan (Output format) with before, after and difference per record, scope used, batch size, and the mutation per batch. 4. **Approve**: show the plan to the owner and wait for an explicit yes. A changed plan needs a new yes. 5. **Pilot**: execute the first small batch (up to 5 records or one product). 6. **Verify**: check `errors`, `userErrors`, returned values, then re-read and compare with the plan. 7. **Continue** in batches, pacing by `throttleStatus`; stop the run at the first unexpected `userErrors` and report. 8. **Log**: write the execution log with before/after values, timestamps and any idempotency keys; the before column is the rollback plan. 9. **Run the quality checklist.** ## Pitfalls and edge cases - **Money is a string in shop currency.** Send `"26.90"`, not 26.9; multi-currency markets may convert or override it, so check market price lists before promising a price abroad. - **Compare-at price is a sale claim.** Setting it creates a visible strike-through; in the EU the reference must follow the Omnibus prior-price rule, so route that decision to `clearance-markdown-planner`. - **One product per `productVariantsBulkUpdate` call.** Variants of different products need separate calls. - **Orders beyond 60 days** are invisible without `read_all_orders`; an empty result is not "no orders". - **Search index lag.** A record changed seconds ago may not match a `query` filter yet; verify by ID. - **Inventory by location.** Quantities live per location and inventory item; a variant-level total hides which location changed. - **Fulfilment writes notify people.** `fulfillmentCreate` has a `notifyCustomer` option; marking orders fulfilled is a customer-facing action, not a data fix. - **Timeouts on writes.** A network timeout does not mean failure; re-read before retrying. ## Rules - Never write without an owner-approved change plan. Reads need no approval. - Never, without a separate explicit approval naming the records: deletes (products, variants, metafields, discounts), refunds, order cancellations, fulfilments that notify customers, `productSet` full syncs, customer data exports, or any scope beyond the task. - Never print, log or store the access token or client secret; never send store data to any service other than the store's own Admin API. - Never invent IDs, values or results; report what the API returned. - Stop on the first unexpected `userErrors` and report instead of working around it. - Store prices, discounts and stock decisions belong to the owner; the agent executes them, it does not choose them. ## Output format ``` CHANGE PLAN · .myshopify.com · API · prepared Task: · scopes used: · records: · batches: × | # | record (GID) | handle / SKU | field | before | after | difference | Mutation per batch: · checks: errors, userErrors, re-read Not included / needs separate approval: Owner approval: or PENDING EXECUTION LOG · · API · started