Run a Shopify Admin GraphQL bulk mutation to update metafield values across thousands of products using stagedUploadsCreate and bulkOperationRunMutation

In-depth guide

Steps

1. Prepare a JSONL file where each line is a valid JSON object containing the mutation variables for one product's metafield update — e.g., `{"input": {"id": "gid://shopify/Product/123", "metafields": [{"namespace": "custom", "key": "size_guide", "value": "...", "type": "single_line_text_field"}]}}`
2. Call `stagedUploadsCreate(input: [{ filename: "metafields_update.jsonl", mimeType: "text/jsonl", httpMethod: POST, resource: BULK_MUTATION_VARIABLES }])` to get a pre-signed upload URL and staged target parameters
3. Upload the JSONL file to the staged upload URL using a multipart POST with the parameters returned by stagedUploadsCreate; the file must be uploaded before calling bulkOperationRunMutation
4. Call `bulkOperationRunMutation(mutation: "mutation productMetafieldUpdate($input: ProductInput!) { productUpdate(input: $input) { product { id } userErrors { field message } } }", stagedUploadPath: $uploadKey)` to start the bulk operation
5. Poll `currentBulkOperation { id status errorCode }` until `status` is `COMPLETED` — also subscribe to the `bulk_operations/finish` webhook to receive notification without polling
6. Download the results JSONL from `currentBulkOperation.url` (available when status is COMPLETED) and parse each line to identify any `userErrors` that indicate failed individual mutations