Shopify Admin Cogs Completeness Audit

Purpose

Scans every variant in the catalog and surfaces those whose inventoryItem.unitCost is missing or zero. Cost of goods sold (COGS) is the foundation for margin reporting, profit-based pricing decisions, and inventory valuation — a single missing cost silently corrupts every downstream calculation. Read-only — no mutations.

Prerequisites

• Authenticated Shopify CLI session: shopify store auth --store <domain> --scopes read_products,read_inventory
• API scopes: read_products, read_inventory

Parameters

Safety

ℹ️ Read-only skill — no mutations are executed. Safe to run at any time. The skill flags missing data; remediation should happen through a follow-up workflow that you control.

Workflow Steps

1. OPERATION: productVariants — query Inputs: first: 250, query: <built from status_filter and vendor_filter>, select sku, price, inventoryQuantity, inventoryItem { id }, product { title, vendor, status, productType }, pagination cursor Expected output: All matching variants; paginate until hasNextPage: false

2. OPERATION: inventoryItems — query Inputs: Batched inventoryItemIds (≤100 per request) Expected output: unitCost { amount, currencyCode }, tracked

3. Filter to variants where unitCost == null or unitCost.amount == 0 (when include_zero_cost: true). Compute potential margin gap as price - 0 = price for the missing-cost variants — this is the fictional margin downstream reports will show.

4. Summarize: count missing, % of catalog, total stock-value impact (sum of inventoryQuantity * price across missing rows since you cannot value them on cost).

GraphQL Operations

graphqlCopy code
# productVariants:query — validated against api_version 2025-01
query VariantsForCogsAudit($query: String, $after: String) {
  productVariants(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        sku
        title
        price
        inventoryQuantity
        product {
          id
          title
          vendor
          status
          productType
        }
        inventoryItem {
          id
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

graphqlCopy code
# inventoryItems:query — validated against api_version 2025-01
query InventoryItemCosts($ids: [ID!]!) {
  nodes(ids: $ids) {
    ... on InventoryItem {
      id
      tracked
      sku
      unitCost {
        amount
        currencyCode
      }
    }
  }
}

Session Tracking

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

On start, emit:

Copy code
╔══════════════════════════════════════════════╗
║  SKILL: COGS Completeness Audit              ║
║  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>

On completion, emit:

For format: human (default):

Copy code
══════════════════════════════════════════════
COGS COMPLETENESS AUDIT
  Variants audited:        <n>
  Missing unit cost:       <n>  (<pct>%)
  Stocked + missing cost:  <n>
  Catalog value at risk:   $<amount> (priced, not costed)

  Top vendors by missing variants:
    <vendor>  Missing: <n>  Stocked: <n>
  Output: cogs_audit_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

jsonCopy code
{
  "skill": "cogs-completeness-audit",
  "store": "<domain>",
  "variants_audited": 0,
  "missing_cost": 0,
  "missing_cost_pct": 0,
  "stocked_missing": 0,
  "value_at_risk": 0,
  "currency": "USD",
  "output_file": "cogs_audit_<date>.csv"
}

Output Format

CSV file cogs_audit_<YYYY-MM-DD>.csv with columns: variant_id, inventory_item_id, sku, product_title, vendor, product_status, price, unit_cost, inventory_quantity, value_at_price, currency

Error Handling

Best Practices

• Run monthly; whenever new vendors or product lines are onboarded, run on day one of activation to catch missing costs before margin reports are trusted.
• Filter by vendor_filter to assign remediation work to the buyer responsible for that vendor's data.
• Pair with inventory-valuation-report — that report will silently treat missing-cost SKUs as worthless inventory unless this audit is clean.
• Treat unitCost = 0 as missing by default. Genuine zero-cost SKUs (free samples, GWP) are rare; tag those with a zero-cost-intentional product tag and exclude them from the audit via vendor_filter or downstream filtering.
• Use the CSV as a worklist: hand it to the merchandising team for cost capture, then re-run weekly until the missing count is zero.