Skip to content
Tutorials Center
My learning

Topics

Lesson 48 of 55 ยท Real-World Projects

Project: Bulk Product Tagger

Build an embedded Shopify app that tags thousands of products by rules: bulk query, a rule engine, bulk mutations, progress and retries, with runnable stand-ins.

Tags are the cheapest way for a merchant to organize a catalog, and the most tedious to maintain by hand. "Everything from vendor Acme under $20 is budget." "Sold-out products get sold-out, and lose summer." A store with 30,000 products cannot do this one row at a time in the admin, which makes it a good first real project: a small embedded app that reads the whole catalog, decides tag changes with merchant-defined rules, and applies them in bulk.

This project ties together several earlier lessons: embedded authentication, bulk operations, mutations and userErrors, rate limits and Polaris. The app code shown here targets Admin API 2026-07 and is read-only: it needs a real development store and the Shopify CLI. The decision logic and the file pipeline are written as runnable stand-ins in plain JavaScript, so you can see every step work without a store.

What we are building

The finished app has one admin page with three states:

  1. Rules. The merchant sees a list of rules ("when the product type is Mug, add drinkware") and can try them.
  2. Preview. The app loads the catalog, applies the rules in memory and shows how many products would change, with a few samples. Nothing is written yet.
  3. Apply. On confirmation the app starts bulk mutations and shows progress until they finish.

The preview step is the most important feature. A tagging tool that changes 30,000 products without showing a plan first is a support ticket waiting to happen.

flowchart LR
    A["Admin page<br/>(rules)"] --> B["Bulk query<br/>products + variants"]
    B --> C["JSONL file"]
    C --> D["Rule engine<br/>(your server)"]
    D --> E["Preview<br/>counts + samples"]
    E -->|"merchant confirms"| F["Variables files<br/>tagsAdd / tagsRemove"]
    F --> G["Bulk mutations"]
    G --> H["Result file<br/>retry failures"]

The rule engine sits between two bulk operations: one reads the catalog, one writes the changes.

Scopes and project setup

Create the app with the CLI as in Creating an App with the CLI and declare the minimum scopes in shopify.app.toml (see Managed Installation and Access Scopes):

TOML
[access_scopes]
scopes = "read_products,write_products"

Reading products and writing tags is all the app does, so it asks for nothing else. No customer or order data is touched, which also keeps the review simpler (App Store Requirements and Review).

Rules must be stored per shop. In the template's Prisma setup, add a small model keyed by shop, as described in Databases and Session Storage in Production:

PRISMA
model TagRule {
  id        Int      @id @default(autoincrement())
  shop      String
  name      String
  position  Int
  condition Json
  addTags   String
  removeTags String
  createdAt DateTime @default(now())

  @@index([shop, position])
}

Rules run in order of position, and every query filters by shop. Keep the condition as structured JSON (field, operator, value) rather than as free text; it is easy to validate and easy to evaluate.

Step 1: read the catalog with a bulk query

A normal paginated query would work for a small shop but costs hundreds of requests for a big one. A bulk query reads everything in the background. The fields come from the rules: product type, vendor, tags, total inventory and variant prices.

JavaScript
// app/jobs/start-catalog-export.server.js (read-only)
const QUERY = `#graphql
  mutation StartCatalogExport {
    bulkOperationRunQuery(
      query: """
      {
        products {
          edges {
            node {
              id
              title
              vendor
              productType
              tags
              totalInventory
              variants {
                edges { node { id price } }
              }
            }
          }
        }
      }
      """
    ) {
      bulkOperation { id status }
      userErrors { field message }
    }
  }`;

export async function startCatalogExport(admin) {
  const response = await admin.graphql(QUERY);
  const { data } = await response.json();
  const { bulkOperation, userErrors } = data.bulkOperationRunQuery;
  if (userErrors.length > 0) {
    throw new Error(userErrors.map((e) => e.message).join("; "));
  }
  return bulkOperation.id;
}

When the job finishes, Shopify calls your bulk_operations/finish webhook (Webhooks in Shopify). The handler stores the result url and marks the preview as ready; it does not do the heavy work inside the webhook request, in line with Reliable Webhook Handlers. The page can poll your own /api/preview-status route, which is cheap because it reads your database and not Shopify.

The file arrives in the JSONL layout from the bulk operations lesson: a product line, then one line per variant with a __parentId.

Step 2: the rule engine

The rule engine is plain logic with no Shopify calls, which makes it easy to test (Testing Shopify Apps). Each rule has conditions (all must match) and lists of tags to add and remove. Rules are applied in order against a running copy of the product's tags, so a later rule can see what an earlier rule did.

Two details save you from nasty bugs:

  • Tags are case-insensitive in Shopify. Sale and sale are the same tag. Compare lowercased values, or you will "add" tags that already exist.
  • Compute a diff, not a result. What you send to Shopify is "add these, remove those", not "the final list". That matters in the next step.
Node.js A rule engine with a dry-run plan

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.

Read the output line by line. The tote has Sale and summer; the "Out of stock" rule adds sold-out and removes summer, and leaves Sale alone. The apron carries a stale low-stock tag, which the "Restocked" rule removes because its inventory is now high. The mug already needs only drinkware. This is the same plan the merchant sees in the preview step.

A word on what is real here. The rule engine is real code you could ship as it is (it uses nothing Shopify-specific). The product list is the stand-in: in the app it comes from the parsed bulk-query file.

Step 3: apply the plan with bulk mutations

For the write step, resist the temptation to send the full tag list with productUpdate. If the merchant edits a product's tags between your export and your write, a full-list update silently erases their change. The tagsAdd and tagsRemove mutations take only the tags to add or remove and leave the rest alone, which matches the diff the rule engine produced.

A bulk operation runs exactly one mutation, so you start two operations: one with tagsAdd, one with tagsRemove. Older API versions allow one bulk mutation at a time per shop, so run them one after the other and start the second when bulk_operations/finish arrives for the first (check your version's documentation for the current limit).

JavaScript
// app/jobs/apply-tags.server.js (read-only)
export async function startBulkMutation(admin, mutation, stagedUploadPath) {
  const response = await admin.graphql(
    `#graphql
    mutation Run($mutation: String!, $path: String!) {
      bulkOperationRunMutation(mutation: $mutation, stagedUploadPath: $path) {
        bulkOperation { id status }
        userErrors { field message }
      }
    }`,
    { variables: { mutation, path: stagedUploadPath } },
  );
  const { data } = await response.json();
  const { bulkOperation, userErrors } = data.bulkOperationRunMutation;
  if (userErrors.length > 0) {
    throw new Error(userErrors.map((e) => e.message).join("; "));
  }
  return bulkOperation.id;
}

export const TAGS_ADD = `mutation call($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node { id }
    userErrors { field message }
  }
}`;

export const TAGS_REMOVE = `mutation call($id: ID!, $tags: [String!]!) {
  tagsRemove(id: $id, tags: $tags) {
    node { id }
    userErrors { field message }
  }
}`;

Before this runs, your server turns the plan into a JSONL variables file and uploads it with a staged upload, exactly as shown in Bulk Operations. Each line is {"id": "...", "tags": [...]}.

Shopify has limits on tags (a maximum count per product and a maximum length per tag). The API reports a violation in userErrors for that product, so your result handling has to cope with some lines failing, which is the next step.

Step 4: progress, results and retries

While the operation runs, the page shows progress. Your server can poll currentBulkOperation(type: MUTATION) and read status and objectCount, or wait for the finish webhook and show a single "done" state. Polling a few seconds apart is fine for one merchant looking at one screen, but remember the lesson on rate limits once many shops use the app at once. Dividing objectCount by the number of lines you uploaded gives the percentage.

After COMPLETED, download the result file. It has one line per input line, and each line holds that mutation's userErrors. A product can disappear between export and write (a merchant deletes it), so some failures are normal. Keep the failed input lines and offer a retry, rather than re-running the whole file. Because tagsAdd and tagsRemove are naturally repeatable (adding a tag that is already there changes nothing), running a line twice is harmless; the broader idea is described in Idempotency.

Node.js The whole JSONL pipeline, from export to retry list

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.

What is real and what is staged: parsing the __parentId layout, building one-object-per-line variables files and matching result lines back to input lines are all how the real files work. The "Shopify ran the file" step is faked here, including the line that fails, and the exact shape of a real result line should be checked against a file from your own development store (the stand-in uses a __lineNumber field to link a result to its input).

Step 5: the admin page

The page itself is a route in the template. Here is a trimmed sketch (read-only, Polaris web components as in Polaris and App Home Design); the full version adds a rules editor.

JSX
// app/routes/app._index.jsx (read-only)
import { useFetcher, useLoaderData } from "react-router";
import { authenticate } from "../shopify.server";
import db from "../db.server";

export const loader = async ({ request }) => {
  const { session } = await authenticate.admin(request);
  const rules = await db.tagRule.findMany({
    where: { shop: session.shop },
    orderBy: { position: "asc" },
  });
  const preview = await db.tagPreview.findFirst({
    where: { shop: session.shop },
    orderBy: { createdAt: "desc" },
  });
  return { rules, preview };
};

export const action = async ({ request }) => {
  const { admin, session } = await authenticate.admin(request);
  const form = await request.formData();
  if (form.get("intent") === "preview") {
    await startCatalogExport(admin);
    return { started: true };
  }
  if (form.get("intent") === "apply") {
    await queueApplyJob(session.shop);
    return { queued: true };
  }
  return null;
};

export default function Index() {
  const { rules, preview } = useLoaderData();
  const fetcher = useFetcher();
  return (
    <s-page heading="Bulk product tagger">
      <s-section heading="Rules">
        {rules.map((rule) => (
          <s-paragraph key={rule.id}>{rule.name}</s-paragraph>
        ))}
      </s-section>
      <s-section heading="Preview">
        {preview ? (
          <s-paragraph>
            {preview.changed} of {preview.total} products would change.
          </s-paragraph>
        ) : (
          <s-paragraph>Run a preview to see what would change.</s-paragraph>
        )}
        <fetcher.Form method="post">
          <input type="hidden" name="intent" value="preview" />
          <s-button type="submit">Run preview</s-button>
        </fetcher.Form>
      </s-section>
    </s-page>
  );
}

(tagPreview is a second small Prisma model, not shown, that stores the counts and sample rows your preview job computed.) Notice that every database read is filtered by session.shop, and the heavy work happens in a queued job, not in the request. A merchant who clicks "Apply" gets an immediate response and watches progress on the page. Component names and the routing helpers change between template versions, so compare with the template you generated. For how the queue and workers behave under load, see Monitoring, Logging and Scaling.

Ideas to extend it

  • Undo. Store the diff of each run (product id, tags added, tags removed) and offer a "revert" that swaps the two lists.
  • Scheduling. Re-run the rules nightly so low-stock tags stay fresh, or trigger a single product update from the products/update webhook.
  • Rule validation. Reject empty conditions and tags that are too long before saving, so the merchant gets feedback in the form and not as a failed bulk line.
  • Billing. Limit free shops to a number of products per run and charge for more, using the patterns in Implementing Billing with the Billing API.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the project use tagsAdd and tagsRemove instead of sending each product's full tag list?

    A full list built from the exported copy can overwrite tags that changed after the export. Adding and removing specific tags leaves the rest untouched.
  2. 2. Why does the project run two bulk mutations instead of one?

    A bulk mutation operation takes one mutation string and a file of variables. Adds and removes use different mutations, so they are two operations, run one after the other.
  3. 3. What should the app do with result lines that contain userErrors?

    A completed bulk mutation can still contain failed lines, for example for products deleted in the meantime. Handle those lines, not the whole file.
  4. 4. Why does the project show a preview before applying anything?

    Writing is the risky step. A dry-run plan from the rule engine costs nothing and shows the effect first.
  5. 5. Why compare tags in lowercase inside the rule engine?

    If you treated Sale and sale as different, you would plan to add tags that already exist.

Summary

  • The app reads the catalog with a bulk query, decides changes with a pure rule engine and writes them with bulk mutations.
  • Always produce a dry-run plan first; the preview is the feature that makes the tool trustworthy.
  • Send diffs (tagsAdd, tagsRemove), not full tag lists, and run one bulk operation per mutation, one after another.
  • Treat the result file as data: count successes, keep failed lines and retry them.
  • Filter every database query by shop, keep heavy work out of requests and ask only for read_products and write_products.

Next: Project: Low-Stock Alerts App.