Shopify Admin Product Tag Bulk Update

*One of collection_id, filter_tag, or query_filter is required.

Safety

⚠️ Step 2 executes bulk tag mutations. tagsRemove is irreversible — if you remove the wrong tag, you must re-add it manually or run this skill again with action: add. Run with dry_run: true to see the full product list before committing. For large catalogs (1000+ products), dry_run is strongly recommended before any removal operation.

Workflow Steps

1. OPERATION: products — query Inputs: first: 250, query built from collection_id, filter_tag, or query_filter; paginate until all matching products fetched Expected output: List of product GIDs and current tag arrays; confirm target set before proceeding

2. OPERATION: tagsAdd — mutation (if action: add) Inputs: id: <productId>, tags: <tags array> per product Expected output: Updated node.id with userErrors

   OR

3. OPERATION: tagsRemove — mutation (if action: remove) Inputs: id: <productId>, tags: <tags array> per product Expected output: Updated node with userErrors

GraphQL Operations

# products:query — validated against api_version 2025-01
query ProductsForTagUpdate($first: Int!, $after: String, $query: String) {
  products(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        title
        tags
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# tagsAdd:mutation — validated against api_version 2025-01
mutation TagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

# tagsRemove:mutation — validated against api_version 2025-01
mutation TagsRemove($id: ID!, $tags: [String!]!) {
  tagsRemove(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: product-tag-bulk-update              ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome, e.g., "143 records returned">

If dry_run: true, prefix every mutation step with [DRY RUN] and do not execute it.

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
OUTCOME SUMMARY
  Products targeted:    <count>
  Tags added/removed:   <tags list>
  Action:               <add|remove>
  Errors:               <count, 0 if none>
  Output:               <filename or "none">
══════════════════════════════════════════════

For format: json, emit a JSON object with this schema:

{
  "skill": "product-tag-bulk-update",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    {
      "step": 1,
      "operation": "<OperationName>",
      "type": "query|mutation",
      "params_summary": "<string>",
      "result_summary": "<string>",
      "skipped": false
    }
  ],
  "outcome": {
    "action": "<add|remove>",
    "tags": ["<tag1>", "<tag2>"],
    "products_targeted": 0,
    "mutations_succeeded": 0,
    "errors": 0,
    "output_file": "<filename|null>"
  }
}

Output Format

CSV file tag-update-<YYYY-MM-DD>.csv with columns: product_id, product_title, action, tags_changed, previous_tags, result.

Error Handling

Best Practices

1. Run dry_run: true before any action: remove — the CSV preview shows exactly which products will lose the tag.
2. To set up a campaign cleanly, run action: add at launch and action: remove at the end — keeping your product tags tidy prevents collection rule drift.
3. Use query_filter: "tag:old-campaign-name" for teardown — it will find exactly the products tagged from the previous run.
4. You can add multiple tags in one run — pass tags: ["sale", "homepage-featured", "clearance"] to apply all three atomically.
5. Tags are case-insensitive in Shopify collection rules but case-preserving in the API — use consistent casing to avoid duplicates like Sale and sale.