Call stagedUploadsCreate mutation with resource BULK_MUTATION_VARIABLES and mimeType application/jsonl to get a staged upload URL and parameters
Upload a JSONL file where each line is a variables object for the target mutation (e.g., productUpdate with metafields array) using a multipart POST to the staged URL
Call bulkOperationRunMutation with the mutation string and stagedUploadPath pointing to the uploaded JSONL
Poll bulkOperationStatus (query currentBulkOperation) until status is COMPLETED; download the result JSONL from the url field to inspect per-object errors
Parse the result file: lines with __lineNumber and errors arrays indicate per-input failures; re-submit a corrected JSONL for failed lines only
Known gotchas
stagedUploadsCreate requires the resource to be BULK_MUTATION_VARIABLES, not BULK_MUTATION or FILE; using the wrong enum returns a 422 from the upload endpoint
The mutation string passed to bulkOperationRunMutation must use $input (not $id or other variable names) and the variable name must match what each JSONL line provides
Only one bulk operation can run at a time per shop; calling bulkOperationRunMutation while another is RUNNING returns a userErrors array — poll and wait or cancel the previous operation first
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