Bulk Operations

bulkOperationRunQuery takes the GraphQL document as a string. The document must contain at least one connection and is executed by Shopify, not by you, so it cannot use variables: build the string in your code. Two arguments exist in 2026-10: query (required) and groupObjects, a non-null boolean whose default is false (see The JSONL output format).

The mutation document below takes the inner query as a GraphQL variable, which keeps the quoting of the inner document out of the way.

Source: bulkOperationRunQuery

The variables carry the Pocket Coffee catalogue export: every active product with its variants, SKUs, prices, stock and selected options.

A successful call answers with status CREATED and the new ID:

Both documents validate against the 2026-10 Admin schema. The response above is the documented shape with Pocket Coffee values; it is not a captured response.

Source: Perform bulk operations with the GraphQL Admin API

The userErrors array is where rejections arrive. Its code is a BulkOperationUserErrorCode: INVALID for a query that breaks a restriction, OPERATION_IN_PROGRESS when an operation of that type is already running, and LIMIT_REACHED when the concurrency limit is full.

Shopify validates the document when you submit it and reports problems in userErrors. The documented restrictions are:

Three arguments that matter when paginating become irrelevant: first is optional and ignored if present, and cursor and pageInfo are optional and ignored. Remove them from queries you move over from paginated code. Use the edges { node { ... } } form, which is what every example in the guides uses.

Because Shopify evaluates the query without a client, errors surface differently from a normal request: a query that is valid but touches a field the app has no scope for fails after it starts, as an operation with status FAILED and code ACCESS_DENIED. That is why the guides advise running the query normally, on a few rows, before wrapping it in a bulk operation.

The nightly order-line export, for the roaster’s planning sheet (the filter is Shopify’s search syntax; the query is the same string you would pass to orders normally):

Source: Perform bulk operations with the GraphQL Admin API

An inventory snapshot per location. Two connections, one nested level, and the available quantity per level:

A range search over a large collection can time out or fail when the search field is not the connection’s sort key. Ask for the matching sort key, here CREATED_AT, which the ProductSortKeys enum offers:

All three documents validate against the 2026-10 schema and pass the restriction checker shown next.

Source: Perform bulk operations with the GraphQL Admin API

Shopify only reports a restriction violation after the round trip, and only one message at a time. Because the restrictions are mechanical, a client can check them offline against the schema it already downloads for validation. The script below validates the document, counts connections, measures the nesting, checks that each connection’s node type implements Node, and rejects top-level node/nodes. It needs graphql version 16 (the version used for this page was 16.14.2) and a schema fetched once from the public introspection proxy:

Source: Perform bulk operations with the GraphQL Admin API

Run against the Pocket Coffee documents and two deliberately invalid ones (a products, collections, products, variants chain, and a top-level nodes), it printed:

The checker mirrors the documented restrictions; it does not replace Shopify’s own validation, which has the final word and may be stricter or looser in corners the documentation does not describe.

Source: Bulk operations: operation restrictions

By default the output used to put every child directly under its parent. Ensuring that grouping is costly: it slows the operation and raises the chance of a timeout. The history is short and worth knowing, because older code and older blog posts assume the old behaviour:

With the default, a parent still precedes its children, but the children of different parents can interleave, as line 5 of the example shows. A reader that assumes adjacency will attach variant 13 to the Starter kit. Build the tree with a map from id to object, which works for both modes, and enable groupObjects: true only when you depend on the grouped layout, for example to flush each product as soon as its last variant has been read:

Source: Bulk operations group objects default changed to false

The download URL is signed, so the request needs no Shopify token and must not carry one. The code below streams the file line by line with the built-in fetch and readline, and rebuilds the tree from __parentId. It is part of the complete client in A complete Node.js client.

Run against the five-line sample above, collectTree returned two roots: "Single-origin beans" with two variants (first SKU PC-ETH-WHL-250) and "Starter kit" with one (PC-KIT). The map keeps every object in memory, so it suits exports that fit in memory; for very large exports use groupObjects: true and flush each root when the next root appears, or write the lines to a database keyed by id and __parentId instead.

Ruby, Python and PHP examples in the Shopify guide make the same point: read the file one line at a time. On a 100 MB file the guide reports about 2.5 MB of memory for the line-by-line reader against 100 MB for loading the file whole.

Source: Download result data

Use bulkOperation(id:). While the status is CREATED or RUNNING, objectCount increases, which also lets you compare progress with what you expect: if a query meant for one month already reports more objects than a month holds, the filter is wrong and you can cancel and resubmit.

Choose the interval from the expected duration. The guide’s rule of thumb: if paginating the same data by hand takes an hour, poll once a minute rather than every 10 seconds. The client in this page starts at two seconds and doubles up to 60. On API versions before 2026-01 the same information comes from the deprecated currentBulkOperation, which returns only the latest operation (pass type: MUTATION to read the latest mutation).

To see everything the app has running, list the operations. The query argument accepts four filters:

sortKey is CREATED_AT (the default, newest first) or COMPLETED_AT, and the connection paginates with the usual cursors.

Source: bulkOperations query reference

Subscribe to the topic bulk_operations/finish (the enum value BULK_OPERATIONS_FINISH) and Shopify sends a webhook whenever any bulk operation on the shop finishes: completed, failed or cancelled, queries and mutations alike. The body is small and carries no result data:

Two details cause bugs. First, status, error_code and type are lowercase in the webhook (failed, timeout, query) while the GraphQL enums are uppercase (FAILED, TIMEOUT, QUERY). Second, the payload has no URL: look the operation up with node(id:) using admin_graphql_api_id and read url and partialDataUrl from it.

The payload does not say which app started the operation, so remember the IDs you created (a database row written when you called bulkOperationRunQuery) and ignore webhooks for IDs you do not know. bulkOperationRunMutation accepts a clientIdentifier string you can use to tag your own operations.

Source: Bulk operations: the finish webhook topic

For an app created with Shopify CLI the recommended subscription lives in shopify.app.toml and applies to every shop that installs the app. The uri can be relative during development, so the tunnel URL that shopify app dev changes on each start does not need editing:

The client_id is a placeholder of zeros and the URLs use the reserved example.invalid domain. topics takes an array of topic names, uri the destination (an HTTPS URL, a relative path resolved against the app URL, an Amazon EventBridge ARN or a Google Cloud Pub/Sub URI), and name an optional label echoed in the X-Shopify-Name header, made of letters, digits, hyphen and underscore, up to 50 characters. include_fields and filter also exist for other topics but bulk finish payloads are already tiny. The last block subscribes to the three compliance topics every App Store app needs.

Running shopify app build --no-input in a project with exactly this file printed pocket-coffee-app built! with no login. Changing topics to a plain string stopped the build with [webhooks.subscriptions.0.topics]: Value must be string[]. A misspelt topic name, however, built without complaint: the CLI checks the shape of the file, and Shopify checks the topic when the app is deployed. Deployment was not run.

Source: Manage webhook subscriptions

An app that cannot use the TOML file, or that needs a different destination per shop, creates a shop-specific subscription with webhookSubscriptionCreate. Shop-specific subscriptions are created with the Admin API and an access token, differ per shop, and, unlike the TOML kind, are deleted by Shopify after repeated delivery failures.

If you move an app from shop-specific to app-specific subscriptions, delete the old subscription to the same topic first (list them with the webhookSubscriptions query), or you will receive every notification twice.

Source: webhookSubscriptionCreate

Every HTTPS delivery carries the header X-Shopify-Hmac-Sha256, the base64 HMAC-SHA256 of the raw request body keyed with the app’s client secret. Verify it before reading the body, answer within five seconds (Shopify’s connection timeout is one second, its total request timeout five seconds, and anything outside the 200 range counts as a failure), and ignore duplicates with X-Shopify-Webhook-Id. When a delivery fails, Shopify retries 8 times over 4 hours.

The length comparison before timingSafeEqual matters: that function throws when the two buffers differ in length, so a forged header of the wrong size would turn into a 500 instead of a 401. With a local test value for the secret, a test script started the server, sent a correctly signed delivery twice, a delivery signed with another key, and a header of the wrong length. It saw 200, 200, 401 and 401, and the handler logged the operation exactly once. If you use the React Router app template, authenticate.webhook(request) does the verification for you before your handler runs; with Express, register the raw body parser before any express.json() middleware, because a re-serialised body never matches the signature.

Source: Verify webhook deliveries

Webhooks can be missed during downtime or handler failures, so combine both. Store the operation ID when you start it, mark it finished when the webhook arrives, and run a periodic job that polls every operation still marked open after a reasonable time. Treat a missed webhook as normal, not as an incident.

Each line is a JSON object whose keys are the variables of your mutation, in the shape the schema expects. A mutation declared as mutation CreateProduct($product: ProductCreateInput!) therefore needs lines of the form {"product": {...}}. One input is one line, however deeply nested its object. The operation does not process the lines serially, so never rely on line order for the result.

The Pocket Coffee seed file creates the two products of the catalogue as drafts:

A second job writes the roast date metafield of the product page badge. metafieldsSet takes an array, so each line carries a metafields array with one entry (the mutation accepts several entries per call; keep a line within the 25 entries the mutation allows):

Source: Bulk import data with the GraphQL Admin API

The ids are placeholders. The two inner mutations are:

Version note. Both bulk-operation guides still show productCreate with a $input: ProductInput! variable and an input: argument. In the 2026-10 schema productCreate takes product: ProductCreateInput! and has no input argument. Validating the guide’s form against the schema gives Unknown argument "input" on field "Mutation.productCreate". Copy the form above, not the one in the guides. Also be careful with status: the ProductStatus enum has ACTIVE, ARCHIVED, DRAFT and UNLISTED, and the value PUBLISHED, which looks natural, does not exist.

Source: productCreate

The server coerces each line against the mutation’s variable definitions and reports a mismatch as an error on that line only, which means you discover bad lines after the upload and the run. The same coercion is available offline from the graphql package, so a client can reject bad files first. The script below reuses the schema downloaded for the query checker:

The two seed files above and the metafield file passed (2 lines checked, 0 rejected). A file with deliberate mistakes produced:

The check covers types and enum values only. Business rules, such as a blank title or a handle that is already taken, are enforced by Shopify when the line runs and come back as userErrors, as shown in the results section.

Source: Create a JSONL file and include GraphQL variables

stagedUploadsCreate returns a signed URL and a list of form parameters for each file you announce. It is the general file-upload mechanism of the Admin API, so its StagedUploadInput has fields that bulk mutations do not use:

The variables for one file:

The answer contains one target. Its url is a Google Cloud Storage host, resourceUrl is null for this resource, and parameters holds the form fields that authenticate the upload: key, Content-Type, success_action_status (201), acl (private), policy, the x-goog-* signing fields. Keep every parameter exactly as returned. The parameter named key is also the value you pass later as stagedUploadPath; it looks like tmp/21759409/bulk/2d278b12-d153-4667-a05c-a5d8181623de/bulk_op_vars.

Source: stagedUploadsCreate

Send a multipart/form-data POST to the target url with each parameter as a form field and the file last. The upload does not go to the Admin API, so it takes no Shopify token. A successful upload answers 201 because of success_action_status.

The shell variables stand for the values of the returned parameters; the actual field list is whatever stagedTargets.parameters contained, so a program should loop over it as the Node.js client below does. Two rules cause most failures:

Source: Upload the JSONL file

bulkOperationRunMutation takes the mutation as a string, the stagedUploadPath (the key value from step 2), and an optional clientIdentifier string you can attach to your own bookkeeping. The mutation string cannot be bulkOperationRunMutation or bulkOperationRunQuery, and it is limited to one connection field.

The response mirrors a bulk query: an operation in CREATED, with type MUTATION. The mutation request itself is not subject to the normal cost limit, so you can start the operation even when the bucket is empty.

Source: Create a bulk mutation operation

A finished bulk mutation also produces a JSONL file at url, and because input and output are both JSONL, each line of the output answers the corresponding line of the input. Every output line holds the normal GraphQL response of that run, plus a __lineNumber that is the zero-based position of the input line. Because lines are not processed in order, use __lineNumber rather than the position in the output file to match results to input.

The sample shows the documented line shape with Pocket Coffee values; the second line is the kind of validation failure that appears as a userErrors entry.

Failure handling is per line. Each line is validated and executed on its own, and its problems are written to the output file:

Only critical system failures end the whole operation with status FAILED, and the documented one is INTERNAL_SERVER_ERROR; that can be transient, so retry. A single bad line therefore never invalidates the batch, and the job is not done when the status says COMPLETED: read the output and count the lines that carry errors or non-empty userErrors.

That is the shape Shopify documents for an unrecognised field (the variable type in the message follows the mutation that the sample ran). If the status is FAILED and partialDataUrl is set, the partial file holds what completed before the failure.

Source: Operation failures