/shopify-category-taxonomy

name: shopify-category-taxonomy
description: >-
  Use when you assign the Shopify Standard Product Taxonomy category, "set the
  product category", "categorize the catalog", or fill the category / taxonomy
  metafields: the admin "Category metafields" panel (Color, Size, Material,
  Caffeine content), a.k.a. product category attributes / taxonomy attributes,
  including the attributes a Google feed asks for.
  Covers bulk classification, discovering a category's attributes and allowed
  values, minting the reserved value metaobjects, and writing them safely. Also:
  "category metafields show blank/null", "my Color attribute won't save". Not
  for bulk CSV data loads (Matrixify can't do this; see shopify-matrixify for
  bulk data).
compatibility: >-
  Shopify Admin API 2025-07 (GraphQL). Needs read_products + write_products AND
  read_metaobjects + write_metaobjects. The metaobjects scopes are the #1 trap:
  without read_metaobjects the values return null and look unwritable.

Shopify Category Taxonomy

Two jobs that chain together: **assign** a product's Standard Product Taxonomy category (Part 1), then **fill** the category metafields that category exposes (Part 2). You cannot do Part 2 until Part 1 is true: the "Category metafields" panel only exists once a product is assigned to a category. Bulk CSV data work lives in the sibling `shopify-matrixify`; the one thing Matrixify **cannot** do is mint the reserved value metaobjects Part 2 needs, which is the entire reason this skill exists.

Store access

**Lane A: custom-app token (scriptable).** Shopify admin → Settings → Apps and sales channels → Develop apps → create an app → grant the four scopes below → install → copy the Admin API access token. Export it; never write it to disk:

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # env, not disk
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '{"query":"{ shop { name } }"}'

Minimum scopes: **`read_products`, `write_products`, `read_metaobjects`, `write_metaobjects`.** The metaobjects pair is not optional (see the null trap).

**Lane B: Shopify CLI OAuth (no stored token).** `shopify store auth --store $SHOPIFY_STORE --scopes read_products,write_products,read_metaobjects,write_metaobjects` then `shopify store execute`. Good for token-less stores where the owner logs in interactively.

**Toolkit preflight.** Lane B rides on the Shopify CLI: run `shopify version` first and install it if missing. For the full Admin GraphQL schema and validated execution, pair this skill with Shopify's official AI toolkit plugin. In Claude Code, check `claude plugin list`; if it isn't there:

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

Recommended, not required: Lane A needs only curl and a token. The toolkit gives your agent the API; this skill gives it the playbook.

Recipes, not scripts

Treat every GraphQL block as a copy-and-adapt recipe your agent writes fresh, runs, and discards. Two rules keep that safe:

1. **Preview before you mutate.** Precede every write with a read-only count of the products in the target category and sanity-check it. A count far above expectation means stop and re-scope. 2. **Non-destructive defaults.** Fill missing only; a blank value in `metafieldsSet` **deletes** the metafield, so only emit non-blank values. Abort the run on first-batch `userErrors`.

Verify against ground truth via the Admin API, not the storefront (CDN-cached, lies about freshness). Never print or commit the token.

Part 1: Assign the category

Set each product's `category` field to a Standard Product Taxonomy category via `productUpdate` (or the Matrixify `Category` column for a pure bulk load).

**CRITICAL: verify every category ID against the official taxonomy source; never guess an ID.** A guessed taxonomy ID resolves to the *wrong* category or a dead node, and it fails silently: the product looks categorized but every downstream attribute, filter, and feed mapping is now wrong. Guessed IDs have burned real product feeds. Resolve the ID by `search:` against `taxonomy { categories }` (Part 2 step 1 shows the query), or from the official taxonomy repo linked in Provenance.

Classification **signal priority** (highest to lowest confidence): **tags** (highest on stores that tag by category: a "Mango" tea tagged `black-tea` is a flavored black, not a fruit infusion, and the tag says so where the title misleads) > **product type** (good when the store populates it, many don't) > **title / vendor** (lexical fallback; a mono-line vendor pins the category, a multi-line one doesn't) > **description** (last resort; verbose and easy to mis-key on flavor words).

Emit a confidence flag per product and split the catalog into high-confidence vs ambiguous (bundles, samplers, cross-category items). Ship the high-confidence rows; route the ambiguous ones to a human review sheet rather than guessing. See the SOP's pull-then-classify steps below.

# preview (read-only): how many products your classifier targets, before any write
query { productsCount(query: "tag:black-tea status:active") { count } }

# then, per high-confidence product, assign the category
mutation Assign($id: ID!, $cat: ID!) {
  productUpdate(product: {id: $id, category: $cat}) {
    product { id category { id fullName } }
    userErrors { field message }
  }
}

Part 2: Fill the category metafields

A category metafield is **not** a plain text/choice value. It is a metafield in the reserved `shopify` namespace, of type `list.metaobject_reference`, whose value is a JSON array of **Metaobject GIDs**. Each of those metaobjects is a reserved taxonomy value (`type: "shopify--<attribute>"`) with a `label` and a `taxonomy_reference` pointing at a