Call the bulkOperationRunQuery Admin GraphQL mutation with a query string that wraps your data query in a bulkOperation context; the query must reference only connection fields and use the implicit __parent_id mechanism for nested resources
Poll the currentBulkOperation query to check status (CREATED, RUNNING, COMPLETED, FAILED, CANCELED); poll on a reasonable interval (e.g., every 5 seconds for small operations, longer for large ones)
When status is COMPLETED, retrieve the url field from currentBulkOperation — this is a short-lived signed URL to a JSONL file on Shopify's CDN; download it promptly before the URL expires
Parse the JSONL file line by line; each line is a JSON object representing one node from the query; nested resources include a __parentId field linking them to their parent node — reassemble the tree if needed
Handle partial failures: if status is FAILED check the errorCode and partialDataUrl; partial data may still be usable depending on the error
For bulk mutations use bulkOperationRunMutation with a JSONL input file uploaded via stagedUploadsCreate; the flow is upload JSONL → get staged upload URL → POST file → call bulkOperationRunMutation with the staged upload URL
Known gotchas
Only one bulk operation can run at a time per shop; if you call bulkOperationRunQuery while another is running, the mutation returns a userError — check currentBulkOperation status before starting a new one
The signed download URL expires after a short window (check current docs for duration); download the file immediately after detecting COMPLETED status rather than storing the URL for later use
Bulk operations are rate-limited and throttled by Shopify; very large catalogs may take minutes to complete — design your polling logic with appropriate timeouts and build in retry if the operation exceeds an expected duration
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp