Shopify Admin Product Tag Bulk Update

Purpose

Adds or removes one or more tags across a set of products in bulk — replacing manual product-by-product editing in the Shopify admin. Use for campaign setup (add summer-sale to a collection before launch), campaign teardown (remove flash-sale after it ends), or catalog reorganization (retag products moving between categories). Tags drive collection rules, marketing segments, and reporting filters, so bulk accuracy matters. Replaces manual Shopify admin bulk editing and CSV import/export workflows.

Prerequisites

• shopify auth login --store <domain>
• API scopes: read_products, write_products

Parameters

Universal (store, format, dry_run) + skill-specific:

*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

graphqlCopy code
# 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
    }
  }
}

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

graphqlCopy code
# 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:

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

After each step, emit:

Copy code
[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):

Copy code
══════════════════════════════════════════════
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:

jsonCopy code
{
  "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.