Bulk-edit a Shopify catalogue with the Admin API and AI

What a bulk edit actually touches

Our earlier guides put the Shopify theme under version control with an AI agent and gave that agent a scoped credential rather than a login. This one is about the other half of the job: changing the data behind the storefront in bulk, safely, when there are thousands of products and one afternoon to do it. It sits in our UK payments and ecommerce work, where a wrong price or a broken redirect is not a cosmetic bug, it is lost revenue.

Shopify gives you a handful of things you will end up changing across the whole catalogue, and an honest constraint on each.

So the first decision is how you run the change, and it is genuinely a decision. A one-off migration a client will run themselves belongs in a tool with a dry-run and a spreadsheet, not a bespoke script. A change you will make every week, driven by a rule and wired into other systems, belongs in a scoped Admin API script you own. Choose by how often it runs.

The safe bulk-change pipeline

Every safe bulk change we run is the same five steps, and the three that matter are the ones people skip when they are in a hurry. Export the before-state to a JSONL file and keep it. Build the change file and validate its schema. Dry-run it, on a development store or a slice of ten products, and read the userErrors it returns. Only then apply the full file. And when it is done, diff the result against the snapshot and keep that snapshot somewhere you can find it, because it is the undo button. The scoped token limits how far a mistake can reach; the snapshot and the dry run limit the damage inside that reach.

Whatever runs the job, it should carry all of this, every time:

How a bulk mutation runs

A bulk mutation is asynchronous, and that shape is the whole trick. You reserve an upload with stagedUploadsCreate, POST a JSONL file where each line is one input, and run bulkOperationRunMutation, which executes your mutation once per line. Then you poll currentBulkOperation until it reports COMPLETED and download a results JSONL, line by line, with successes and userErrors separated. The recovery model falls out of that: re-run only the lines that failed. Shopify: bulk import with the GraphQL Admin API

Three limits decide how you shape the job. The GraphQL Admin API restores 100 points a second on a standard plan, 200 on Advanced, 1,000 on Plus and 2,000 on Enterprise, and no single query may cost more than 1,000 points, so a naive loop throttles itself long before it throttles the store. Shopify: API rate limits. metafieldsSet takes at most 25 metafields per call. And since API version 2026-01 a shop can run up to five bulk mutations at once, where older versions allowed one of each type, so parallelism is a version decision, not a guess. Inventory is the exception with no bulk path, which is where a throttled cron that updates a batch on a schedule earns its place over a single doomed request.

// bulk-price.mjs: apply a price change to many products in one bulk mutation.
// Step 0, always: export the before-state with bulkOperationRunQuery and keep it.
// price.jsonl, one line per product, each line one productVariantsBulkUpdate input:
//   {"productId":"gid://shopify/Product/123",
//    "variants":[{"id":"gid://shopify/ProductVariant/456","price":"19.99"}]}

// 1. Reserve an upload with stagedUploadsCreate, POST price.jsonl to it, keep the path.
// 2. Run the mutation over every line of the file:
const VARIANT_UPDATE = `mutation call($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
    userErrors { field message }
  }
}`;

const run = await admin(`mutation bulk($path: String!, $q: String!) {
  bulkOperationRunMutation(mutation: $q, stagedUploadPath: $path) {
    bulkOperation { id status }
    userErrors { field message }
  }
}`, { path: stagedUploadPath, q: VARIANT_UPDATE });

// 3. Poll currentBulkOperation until COMPLETED, download the results JSONL, and
//    re-run only the lines that returned a userError. The step-0 export is the
//    rollback: re-apply it exactly the same way if the change was wrong.

What breaks in production

For this guide we went through our own Shopify catalogue work. Client names are withheld and described by sector. These are the bulk-change failures that actually cost time, and the rule each one taught.

1. Export before you write, or you cannot roll back. A Shopify mutation has no undo. The before-state JSONL is the only thing that turns a mistake into a re-run instead of an incident.
2. Dry-run against the userErrors, not against your confidence. Run the file on a subset or a development store and read what comes back per line. The errors are cheaper to find before the full run than after it.
3. Treat redirects and handles as catalogue data. Changing a handle changes a URL. Validate every redirect target, and generate the redirect when the handle moves, or search rankings pay for it.

The Catalogue Change Risk Score

Before a bulk change runs, this is the triage we use. It does not measure whether the change is a good idea. It measures how bad an afternoon it could turn into, and whether to run it or build the safety net first.

A scripted price change with an export, a dry run on a dev store and per-line error handling scores zero or one. The same change typed straight into a live store with no export, because it was quicker, scores nine before it has touched a product.

A real boundary: the API will not bulk everything

The boundary that catches every high-SKU store is that Shopify’s convenient bulk tools stop short of what you actually need. On a UK caravan, motorhome and campervan parts retailer we run, with tens of thousands of variant-level SKUs, the tidy mutation, productVariantsBulkUpdate, only handles one product per call, and there is no bulk mutation for inventory at all. That is not a bug to work around, it is the shape of the platform, and the honest answer is to build the pipeline the API rewards.

What our production record shows is that this pipeline scales. On that store we read roughly 36,000 products through a single bulk query, and a throttled price and inventory job moved about 12,000 products in five to six minutes, which extrapolates to a full six-figure catalogue in under an hour, with the rate limit a non-issue because bulk operations restore fast. It is the same discipline the team brings to a five-year custom Shopify build for an EU beauty brand: read first, change deliberately, keep the way back.

Recommendations by business type

Primary sources

• Shopify: bulk import data with the GraphQL Admin API
• Shopify: perform bulk operations with the GraphQL Admin API
• Shopify: bulkOperationRunMutation
• Shopify: productVariantsBulkUpdate
• Shopify: metafieldsSet
• Shopify: stagedUploadsCreate
• Shopify: urlRedirectCreate
• Shopify: API rate limits
• Shopify: API versioning
• Matrixify: how it works, including the dry-run import

Technical and operational guidance, not legal advice.