Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 55 ยท Admin GraphQL API

Bulk Operations

Export or update thousands of Shopify objects with bulk operations: bulkOperationRunQuery, JSONL results, polling or webhooks, staged uploads and a runnable JSONL parser.

Paginating through 200,000 products with first: 250 means 800 requests, each one spending points from your bucket (see Rate Limits and Query Cost). Updating 50,000 prices one mutation at a time is worse. Shopify offers a different tool for jobs this size: the bulk operation. You hand Shopify a query or a mutation, Shopify runs it on its own infrastructure in the background, and you download the result as a file when it is done.

Bulk operations are the right choice for exports, full catalog syncs, migrations and mass edits. They are the wrong choice for anything interactive, because they are asynchronous: you start one, wait, and collect the output later. This lesson covers the query side (bulkOperationRunQuery), the odd-looking JSONL result format, how to learn that the job finished, and the mutation side with staged uploads. Examples target Admin API 2026-07. The real requests are read-only; the JSONL parser at the end is a runnable stand-in that processes data in the same shape as a real result file.

The life of a bulk query

A bulk query has four steps:

  1. You send the bulkOperationRunQuery mutation with the query text.
  2. Shopify validates it and returns a bulkOperation with status CREATED, or userErrors explaining what is wrong.
  3. Shopify runs it. The status moves to RUNNING, then to COMPLETED (or FAILED, CANCELED, EXPIRED).
  4. You read the url of the result file and download it.
sequenceDiagram
    participant App as Your app
    participant S as Shopify
    App->>S: bulkOperationRunQuery(query)
    S-->>App: bulkOperation { id, status: CREATED }
    Note over S: runs in the background
    S-->>App: webhook bulk_operations/finish
    App->>S: node(id) { status, url }
    S-->>App: status COMPLETED, url
    App->>S: GET url (JSONL file)

Start the job, wait for the finish signal, then fetch the status and download the file.

This is the request that starts it (read-only):

GRAPHQL
mutation StartExport {
  bulkOperationRunQuery(
    query: """
    {
      products {
        edges {
          node {
            id
            title
            variants {
              edges {
                node {
                  id
                  sku
                  price
                }
              }
            }
          }
        }
      }
    }
    """
  ) {
    bulkOperation {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

The inner query is a string containing a normal GraphQL query, with a few differences from a regular one:

  • You do not paginate. Connections are written as edges { node { ... } } without first or after, and Shopify walks the whole list for you.
  • The number of connection fields and the depth of nesting are limited. A bulk query may contain only a handful of connections and only a couple of levels of nesting, so a very wide or deep query is rejected with a userError. Check the current limits in Shopify's documentation when you design the query.
  • Do not mix unrelated top-level fields; keep the query focused on one tree of data.

Just like any mutation, always check userErrors. See Mutations and userErrors.

Finding out that it finished

There are two ways, and one of them is clearly better.

Polling. Ask Shopify about the job every few seconds. You can query the operation by id with node(id: ...) (casting with ... on BulkOperation), or ask for the current one with currentBulkOperation:

GRAPHQL
query CheckExport {
  currentBulkOperation(type: QUERY) {
    id
    status
    errorCode
    objectCount
    fileSize
    url
    partialDataUrl
  }
}

Polling works, but it spends points and adds delay. If you poll, use a gentle interval (several seconds, growing over time) and stop when the status is no longer CREATED or RUNNING.

Webhook. Subscribe to the bulk_operations/finish topic. Shopify calls your server once when the job reaches a final state, and the payload contains the operation's id and status. Then you make one request for the url. This is cheaper, faster and scales better across many shops. Webhook setup is covered in Webhooks in Shopify, and the signature check in Verifying Webhook Signatures.

A few details worth remembering:

  • url points to the result file once the status is COMPLETED. It is a temporary link and expires after a while (about a week at the time of writing), so download promptly and store what you need.
  • A job that stops with FAILED may still offer a partialDataUrl containing the lines produced before the failure.
  • errorCode tells you why a job failed (for example a timeout or an internal error).
  • Older API versions allow only one running bulk query per shop at a time; newer versions allow several. Read the documentation for your version, and handle the userError that says another operation is in progress by waiting and retrying.

The JSONL result format

The result is not one big JSON document. It is JSONL (JSON Lines): one complete JSON object per line, no commas between lines, no outer array. This lets you process a gigabyte file as a stream without loading it all into memory.

The surprising part is how nesting is represented. A product with three variants does not produce one object with an array inside. It produces four lines: one for the product and one for each variant. Every child line carries a __parentId that points to the id of the line above it:

Text
{"id":"gid://shopify/Product/1","title":"Canvas Tote"}
{"id":"gid://shopify/ProductVariant/11","sku":"TOTE-S","price":"18.00","__parentId":"gid://shopify/Product/1"}
{"id":"gid://shopify/ProductVariant/12","sku":"TOTE-L","price":"22.00","__parentId":"gid://shopify/Product/1"}
{"id":"gid://shopify/Product/2","title":"Enamel Mug"}

Children appear after their parent, and Shopify keeps them together, so a streaming reader can rebuild the tree with a little bookkeeping. Which collection a child belongs to (variants, images, and so on) can be read from the type inside its global id (gid://shopify/ProductVariant/12).

Node.js Rebuild nested objects from JSONL lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The stand-in keeps the whole result in memory to stay short. In a real app with a big file, read the HTTP response as a stream, split it into lines, and process each product when its children are complete (a new root line, or the end of the file, tells you the previous one is finished). That keeps memory flat whatever the file size.

Bulk mutations

To change many objects, use bulkOperationRunMutation. The idea is: you write one mutation with variables, and you upload a JSONL file in which each line is one set of variables. Shopify runs the mutation once per line.

Because the file is large, you do not send it inside the GraphQL request. You upload it to storage that Shopify gives you, a staged upload:

  1. Call stagedUploadsCreate with resource: BULK_MUTATION_VARIABLES, a filename, a MIME type of text/jsonl and httpMethod: POST. The response lists a url and parameters (form fields).
  2. Upload the JSONL file to that url as a multipart form using those parameters. One of them is the key.
  3. Call bulkOperationRunMutation with the mutation string and stagedUploadPath set to that key.
GRAPHQL
mutation StartBulkUpdate($path: String!) {
  bulkOperationRunMutation(
    mutation: "mutation call($input: ProductInput!) { productUpdate(input: $input) { product { id } userErrors { field message } } }"
    stagedUploadPath: $path
  ) {
    bulkOperation {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

A variables file for it looks like this, one object per line (read-only):

Text
{"input":{"id":"gid://shopify/Product/1","tags":["summer"]}}
{"input":{"id":"gid://shopify/Product/2","tags":["summer","sale"]}}

The mutation you pass must match the API version and the input type of the fields you use, so check the schema for your version before sending thousands of lines. The result file of a bulk mutation has one line per input line, each holding that mutation's output, including its userErrors. A bulk mutation can partly succeed, so read the result and handle the failed lines, exactly like the partial-failure handling in Mutations and userErrors. Safe retries matter here too; see Idempotency.

Node.js Build the variables file for a bulk mutation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

When to use what

Situation Best tool
Show 20 products in the admin UI Normal paginated query
Export every order from last year Bulk query
Change tags on 40,000 products Bulk mutation
React when one product changes Webhook
Check if a single order exists Normal query by id

Bulk operations trade latency for volume. Use them when the job is big and nobody is waiting on it in a browser tab.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a bulk query result represent a product with three variants?

    JSONL puts each object on its own line. Nested objects are separate lines linked to their parent through __parentId, which lets you stream the file instead of loading it whole.
  2. 2. What is the main advantage of the bulk_operations/finish webhook over polling?

    Shopify tells you once when the job reaches a final state. Polling works but costs requests and adds delay.
  3. 3. In a bulk mutation, where do the per-object values go?

    You write one mutation with variables and upload a file where each line is one set of variables. stagedUploadPath tells Shopify which uploaded file to use.
  4. 4. A bulk mutation finished. What should your code do with the result file?

    The operation can complete while individual lines failed. Each result line contains that mutation's output, including userErrors.

Summary

  • Bulk operations run a query or mutation on Shopify's side and deliver a file, which suits exports, syncs and mass edits.
  • bulkOperationRunQuery takes a query without pagination arguments; check userErrors and the documented limits on connections and depth.
  • Learn about completion with the bulk_operations/finish webhook (preferred) or by polling currentBulkOperation; the result url is temporary.
  • Results are JSONL: one object per line, with children linked to parents by __parentId; parse them as a stream.
  • Bulk mutations use stagedUploadsCreate, a JSONL file of variables, and bulkOperationRunMutation with stagedUploadPath; always inspect each result line for userErrors.

Next: Storefront API Basics.