Admin GraphQL API

An app can only read or write the objects covered by the access scopes it was granted at installation. For the Pocket Coffee integration the relevant scopes are read_products and write_products (products, variants, collections), read_inventory and write_inventory (inventory items and levels), read_orders (orders), read_customers and write_customers (customers) and read_metaobjects, write_metaobjects for metaobjects. Metafields follow the scope of the resource that owns them.

By default read_orders and write_orders cover only orders created in the last 60 days. Older orders require read_all_orders declared alongside read_orders or write_orders, and Shopify approval. Reading personal customer data (name, email, address) from orders and customers is additionally subject to protected customer data requirements for public apps. Scopes are declared in shopify.app.toml, as described in the page on authentication and access scopes (Authentication and Access Scopes).

A request that needs a scope the app does not have is answered with HTTP 200 and an error whose extensions.code is ACCESS_DENIED; do not branch on a 403 to detect a missing scope. On the GraphQL Admin API a 403 means the store has been marked as fraudulent. Starting on 2027-01-01 a request that presents the non-expiring offline access token of a public app also receives 403, with the message Non-expiring access tokens are no longer accepted for the Admin API.

Source: Shopify: access scopes

Source: Shopify: API response status and error codes

Source: Shopify: GraphQL Admin API reference, client libraries

Source: Shopify CLI: app execute

The CLI help of the installed Shopify CLI 5.0.0 (shopify app execute --help, shopify store execute --help) was read and matches the flags listed above; the commands themselves need a login and were not executed.

The minimal request, with obvious placeholders for the shop and the token:

Source: Shopify: GraphQL Admin API reference, authentication

The same operation from an embedded app built on the React Router template. The #graphql marker on the first line of the template string is what the code generation tooling uses to find operations in source files.

Source: Shopify: React Router app template

Always put an explicit version in the URL. When a request targets a version that is no longer accessible, Shopify does not fail: it falls forward and answers with the oldest accessible stable version. A request to the retired 2025-10 is therefore served by 2026-01 today, with a schema that may differ from the one the code was written for, and the only signal is the response header. Check it in tests and in monitoring:

Source: Shopify: About Shopify API versioning, making requests to an API version

The versioning page spells the header X-Shopify-API-Version for API responses and X-Shopify-Api-Version on webhook deliveries; HTTP header names are case-insensitive, so both are the same header for a client.

Official libraries pin the version for you. In the React Router template it is apiVersion: ApiVersion.October26 in shopify.server.ts, and the same constant feeds the code generation configuration in .graphqlrc.ts (shopifyApiProject({ apiType: ApiType.Admin, apiVersion: ApiVersion.October26, ... })). A version bump is therefore a one-line change plus a regeneration of the types, and the compiler then reports every operation the new schema no longer accepts. Other places that carry an API version in an app are the api_version of [webhooks] in shopify.app.toml, the api_version of each extension in its shopify.extension.toml, and the version in any hand-written URL.

When part of the API becomes unnecessary, unsafe or outdated it is deprecated in all supported stable versions at once and announced in the developer changelog with migration guidance. It is removed in a subsequent release, for example something deprecated in 2026-10 can be removed in 2027-01. Because versions overlap by at least nine months, there is always time to migrate before removal. Deprecated fields carry the @deprecated directive in the schema, so introspection and the explorer show them with a reason. In the 2026-10 schema, for example, the query currentBulkOperation is deprecated in favor of bulkOperations, the mutation collectionAddProducts in favor of collectionUpdate, productChangeStatus in favor of productUpdate and fulfillmentCreateV2 in favor of fulfillmentCreate. The automaticDiscounts query is announced to be removed in 2027-01.

An entire API can be deprecated, not only fields; a deprecated API stays available but unsupported and may stop working at any time. Apps are warned through alerts in the Dev Dashboard, deprecation warnings in explorer tools, the changelog, the reference and, for imminent breaking changes, the emergency developer contact. Deprecated calls are attributed to the app whose access token made them, so do not reuse an app’s token in Postman collections or scripts: they raise alerts against the app. An app that keeps using unsupported resources after the upgrade deadline is delisted from the Shopify App Store, and users are blocked from installing it for at least seven days.

Source: Shopify: About Shopify API versioning, deprecation practices

Source: Shopify developer changelog

A quarterly upgrade is mostly mechanical when the operations live in source files that tooling can see:

Source: Shopify: shop query

Objects are identified by global IDs, not by the numeric IDs of the REST API. A global ID has the form gid://shopify/{ObjectName}/{id}, for example gid://shopify/Product/123. Some child objects need parameters, such as gid://shopify/InventoryLevel/123?inventory_item_id=456. Treat a global ID as an opaque string that is built by Shopify: store and pass it as returned and only construct one when migrating from a REST numeric ID (see the migration section).

Every object that implements the Node interface can be fetched by ID through the root fields node(id:) and nodes(ids:). Use inline fragments to select type-specific fields. nodes returns a list in the same order as the IDs, with null for IDs that do not resolve.

Source: Shopify: Global IDs in Shopify APIs

The ID values above are placeholders. The array argument ids follows the general limit that input arrays accept at most 250 items on every Shopify API.

For products, variants, collections, customers and a few other types, a ...ByIdentifier root field looks an object up by ID, handle or a unique metafield value, which saves a search round trip.

Source: Shopify: productByIdentifier query

Connection root fields (products, productVariants, orders, customers, collections, inventoryItems, and so on) accept a query string with Shopify’s search syntax, a sortKey enum specific to the connection, and reverse. The same grammar is used by the REST query parameter, webhook delivery filters and the admin search box. The grammar in short:

Source: Shopify: Search query syntax

Two behaviors cause silent bugs. A search on a field name that does not exist is ignored and the connection returns all results, so a typo in a filter does not raise an error; schema validation cannot catch it because the query argument is a plain string. And range searches on a large collection can time out or fail when the search field differs from the connection sort key, in which case set sortKey to the field being searched.

Source: Shopify: productVariants query

Orders show the date-range pattern, with the sort key matching the filtered field. This is the query Pocket Coffee uses to reconcile the day’s orders. It needs the read_orders scope and returns only orders from the last 60 days unless the app also has read_all_orders.

Source: Shopify: orders query

Customers are searched with tags in the same way. Reading email and other personal fields is protected customer data for public apps. The Coffee Club members of Pocket Coffee (for example ada@example.test) are the customers with the tag Coffee Club:

Source: Shopify: customers query

Counts are separate root fields (productsCount, ordersCount, customersCount, productVariantsCount) that return a Count object with a number and a precision. They accept the same query string and an optional limit. Counts are accurate up to 25,000: for larger sets they return 25,001, which means "more than 25,000".

Source: Shopify: productsCount query

Standard GraphQL features work as in any server. Fragments remove repetition, aliases let one request fetch the same field twice with different arguments, and the standard @include(if:) and @skip(if:) directives turn parts of the selection on and off from variables. Besides the built-ins the schema defines @idempotent(key:) (see the section on idempotency), @accessRestricted(reason:), which marks schema elements with restricted access, @deprecated(reason:) and @oneOf, which marks input objects of which exactly one field must be supplied.

Source: Shopify: GraphQL Admin API reference

For the language itself (fragments, variables, directives, introspection, validation rules) see the GraphQL reference of this documentation, in particular Queries and Fields, Variables, Directives and Fragments, Pagination and Response and Error Handling.

The product model has three tiers: the product, its options (such as origin or size, each with values) and its variants, which are the purchasable combinations of option values and carry the SKU, price, barcode and inventory. The REST endpoints that list, create, update and delete products have been deprecated since REST version 2024-04 in favor of this model, and the old variant mutations productVariantCreate and productVariantUpdate no longer exist in the 2026-10 schema. The incremental mutations are productCreate, productUpdate, productDelete, productOptionsCreate (and productOptionUpdate, productOptionsReorder, productOptionsDelete), productVariantsBulkCreate, productVariantsBulkUpdate, productVariantsBulkDelete and productVariantsBulkReorder. For an external system that is the source of truth the declarative productSet replaces the whole state of a product in one call.

productCreate takes a product argument of type ProductCreateInput. It creates the product with one standalone default variant unless productOptions are supplied. The Pocket Coffee "Starter kit" is a simple product: create it, then set the price of its default variant with productVariantsBulkUpdate, exactly as the React Router app template does.

Source: Shopify: productCreate mutation

Source: Shopify: productVariantsBulkUpdate mutation

The IDs in the variables are placeholders: they would come from the productCreate response. productVariantsBulkCreate and productVariantsBulkUpdate accept up to 2,048 variants per call, productVariantsBulkDelete up to 250. With productVariantsBulkCreate the strategy argument controls the standalone default variant: REMOVE_STANDALONE_VARIANT removes it so that all 2,048 slots are usable, while DEFAULT and PRESERVE_STANDALONE_VARIANT keep it.

"Single-origin beans" has three options and 18 variants. When the catalogue is maintained in a warehouse or PIM system, productSet is the right mutation: it creates or updates the product and replaces the lists of options and variants with exactly what is sent, and it changes only the scalar fields that are present. It takes an input of type ProductSetInput, a synchronous flag and an optional identifier (ID, handle or custom ID) to update an existing product. With synchronous: false it returns a productSetOperation to poll, which is how large products are handled.

Source: Shopify: productSet mutation

The variables are generated from the catalogue definition rather than typed by hand. The script below builds the 18 variants, the SKUs (PC-<ORIGIN>-<GRIND>-<SIZE>) and the prices of the running example: 8.90 for 250 g and 29.90 for 1 kg, plus 1.00 per 250 g for Ethiopia (9.90 for 250 g and 33.90 for 1 kg).

Source: Shopify: About products and collections

This script was run, and its output validated against the 2026-10 schema as the variables of the SyncBeans mutation: 18 variants, SKUs from PC-ETH-WHL-250 to PC-BRA-FIL-1KG, and ProductSetInput accepted every field. The first two variant entries of the generated document are:

Source: Shopify: ProductSetInput

Because productSet replaces list fields, omitting a variant that exists in the store deletes it. That is the intent when the external system is the source of truth, and the main pitfall otherwise: for targeted edits use the incremental mutations. The cost of productSet is dynamic (10 points, plus 0.2 per variant, 0.6 per variant file, 0.4 per metafield and 1.9 per product file), so by the published formula the Pocket Coffee product costs 10 + 18 x 0.2 = 13.6 points; this is a calculation from the formula, not a measured value. The mutation supports up to 2,048 variants on every plan.

The roast date shown by the "Roast date badge" of Pocket Coffee is a product metafield, custom.roast_date of type date. metafieldsSet writes up to 25 metafields in one call (with a total payload of at most 10 MB), creating or updating each by owner, namespace and key. The operation is atomic: if one metafield is rejected, none is persisted. Since 2024-07 it supports compare-and-set: pass the compareDigest of a previously read metafield and the value is only written if the stored one still matches, or pass null to write only when the metafield does not exist yet. Since 2026-09-15 the cost of the mutation is 10 points plus a weight for every distinct owner resource, so batch writes by owner rather than sending one call per metafield.

Source: Shopify: metafieldsSet mutation

Source: Shopify developer changelog: dynamic complexity cost for metafieldsSet

Metafield definitions, metaobjects and how a theme reads these values are covered in the page on metafields and metaobjects (Metafields and Metaobjects).

Tags are added and removed with tagsAdd and tagsRemove, which take the global ID of a resource that supports tags (for example a product, an order or a customer; a resource that does not support tagging returns a resource-not-found error). Adding the Coffee Club tag is how Pocket Coffee enrolls a customer in the club:

Source: Shopify: tagsAdd mutation

Inventory is a separate object graph: a variant has an InventoryItem, which has an InventoryLevel at each location with quantities by name (available, on_hand, committed, and so on). To set an absolute quantity, use inventorySetQuantities; for a relative change use inventoryAdjustQuantities. Both require the write_inventory scope and, since API version 2026-04, the @idempotent directive (see the next section). inventorySetQuantities takes a reason, the quantity name and a list of quantities; each entry names an inventoryItemId, a locationId and the new quantity.

Source: Shopify: inventorySetQuantities mutation

As of 2026-04, changeFromQuantity is mandatory on every entry of quantities: the mutation only updates a quantity when the stored value equals changeFromQuantity (a compare-and-swap) and otherwise returns the user error CHANGE_FROM_QUANTITY_STALE, instead of overwriting a concurrent change. Passing null explicitly skips the check, which is acceptable only when the integration is the single source of truth for that stock; omitting the field is an error. The field is already accepted by the 2026-01 schema, so the same document works on all supported versions.

productUpdate takes a product argument (type ProductUpdateInput) that carries the id, and an optional identifier argument to address the product by handle or custom ID instead. Older examples, including one on the official Global IDs page, still show the pre-2024-04 form with an input argument; that form is rejected by the 2026-10 schema, as the validation section shows.

Source: Shopify: productUpdate mutation

Webhook subscriptions can be created with webhookSubscriptionCreate (and listed with webhookSubscriptions), but apps should declare them in shopify.app.toml, which is covered in the page on webhooks and events (Webhooks and Events). For reading or writing more than a few thousand objects, use the bulk operations bulkOperationRunQuery and bulkOperationRunMutation, which are not subject to the single-query cost limit (Bulk Operations).

Every field in the schema has an integer cost. By default the cost depends on what the field returns:

Source: Shopify: GraphQL Admin API rate limits, cost calculation

Shopify reserves the right to set manual costs on fields. The cost of a query is the maximum cost of the fields it selects, so the cheapest queries ask for few fields and small pages. Because a connection is sized by its page size, a nested connection multiplies the size of the connections above it: the error sample in the reference shows a query whose cost is 2003, over the limit of 1000.

Each query is priced twice:

A single query may not exceed 1,000 points, whatever the plan. This is checked on the requested cost before execution. The only way to know the true cost of a query is to run it and read the response; it cannot be computed offline.

Every response includes the cost under extensions.cost:

Source: Shopify: GraphQL Admin API rate limits, GraphQL response

maximumAvailable is the bucket size, currentlyAvailable the points left, restoreRate the points returned per second. With the header Shopify-GraphQL-Cost-Debug: 1 the same object has a fields array with one entry per field (path, definedCost, requestedTotalCost, requestedChildrenCost), which shows which part of the query is expensive. Use it while developing a query, not in production.

Rejections are HTTP 200 responses with an errors array; the Admin API does not use 429 for rate limiting. Branch on errors[n].extensions.code:

Source: Shopify: API response status and error codes

Source: Shopify: GraphQL Admin API reference, status and error codes

Some mutations do not use the flat cost of 10:

Source: Shopify developer changelog: dynamic complexity cost for productCreate and productUpdate

Source: Shopify developer changelog: dynamic complexity cost for productSet

Source: Shopify: API limits

The practices the documentation recommends are generic: ask only for the data the app needs, cache, spread requests evenly, catch errors instead of hammering the API, use the cost metadata in responses to adapt, and stop making requests until enough time has passed, with a recommended backoff of one second. The Pocket Coffee client below applies them. It is built on @shopify/admin-api-client. That client’s retries option only repeats requests answered with HTTP 429 or 503, which the GraphQL Admin API does not use for throttling, so a THROTTLED response has to be handled by the application: the run function waits until the bucket would hold the requested cost again, never less than one second, and gives up after five attempts. allProducts pages through the active products with the cursors described in the next section.

Source: Shopify: API limits, avoiding rate limit errors

Production code usually adds jitter to the wait, a queue that serializes calls per shop, and a circuit breaker for repeated failures. In a real app the client is created once per shop with the access token of that shop:

Source: Shopify: Admin API client

The pagination and throttling logic was run for real, with the real @shopify/admin-api-client 2.0.1, against a local HTTP server that stands in for the shop. The stand-in checks the path and the token header, validates every incoming query against the real 2026-10 schema, serves five products, and answers every third request with a THROTTLED error. It was started with customFetchApi redirecting the client to it. The numbers in extensions.cost come from the stand-in and are not Shopify costs. Run with a page size of two:

Source: Shopify: API limits

The third request was throttled, the client waited one second and the retry returned the last page (1033 ms on the clock). Calls to the real API with a token were not executed.

Design guidelines that follow from the cost model:

REST limits are request based, still a leaky bucket, per app and store:

Source: Shopify: REST Admin API rate limits

Source: Shopify: Global IDs in Shopify APIs, finding equivalent IDs between REST and GraphQL

For objects whose ID is parameterized (such as InventoryLevel) the numeric part alone is not enough to rebuild the global ID, so persist the global ID when you first see it, or read legacyResourceId together with the required parameters.