A practical reference for authentication, permissions, request limits and safe stock updates. Normal warehouse work does not require writing API requests.
Where to start
Clients → the intended client
GraphQL and versions
Shopify's GraphQL Admin API describes the records and operations used by modern integrations. Use the version your deployed connection supports, not whichever version a search result happens to show. The versioned references here cover 2026-07; a different deployed version needs its matching documentation.
Authentication is not permission
| State | What it means | Safe next step |
|---|---|---|
| Authentication | Proves which app is making the request for which store. | Use the installed app and the correct connection method. |
| Scopes | Define the data and operations the merchant has approved for that app. | Compare the approved grant with the required permissions guide. |
| Organisation | The client credentials grant is for stores in the app's own Shopify organisation. | Do not exchange another merchant's credentials or reuse an unrelated app. |
| Location | Stock and fulfilment work belong to specific Shopify locations. | Check the mapped location before interpreting inventory or order eligibility. |
Request limits and pages
Shopify limits GraphQL work by query cost. Large order or catalogue reads also need pagination. A running sync may be reading several pages or waiting for capacity; repeatedly starting it is not a shortcut.
Read the error, not just the HTTP status
A GraphQL response can use HTTP 200 and still include errors or mutation userErrors. A timeout can also leave the outcome uncertain. The integration owner must check the actual result, not infer success or failure from the status alone.
Stock updates need concurrency protection
Physical-count corrections use the intended on-hand quantity, not available stock as a substitute. In the referenced 2026-07 API, inventorySetQuantities requires an @idempotent key and supports compare-quantity checks. Turning off those checks or sending a new request after an uncertain result can cause an incorrect second change.
This is a reference, not a warehouse workaround
Use StoreFulfil's supported sync, adjustment and recovery controls for ordinary work. Different Shopify mutations have different retry behaviour; do not assume that a second fulfilment request is harmless.