shopify-admin-inventory-aging-report

name: shopify-admin-inventory-aging-report role: merchandising description: "Read-only: categorizes inventory into aging buckets (0-30, 31-60, 61-90, 90+ days) based on time since last sale or receipt." toolkit: shopify-admin, shopify-admin-execution api_version: "2025-01" graphql_operations: - productVariants:query - orders:query - inventoryItems:query status: stable compatibility: Claude Code, Cursor, Codex, Gemini CLI

Purpose

Categorizes all inventory into aging buckets based on how long items have been sitting without selling. Calculates carrying cost exposure by bucket to prioritize markdown or liquidation decisions. Goes deeper than dead-stock identification by providing aging granularity. Read-only — no mutations.

Prerequisites

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

Parameters

Safety

ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.

Workflow Steps

1. OPERATION: productVariants — query Inputs: first: 250, select id, sku, inventoryQuantity, inventoryItem { id, unitCost }, product { title, vendor, status }, pagination cursor Expected output: All variants with stock and cost data

2. Filter to variants with inventoryQuantity > 0

3. OPERATION: orders — query Inputs: query: "created_at:>='<NOW - 365 days>'", first: 250, select createdAt, lineItems { variant { id }, quantity }, pagination cursor Expected output: Sales history to determine last-sold date per variant

4. For each stocked variant, determine aging:

   • Find most recent order containing this variant → last_sold_date
   • If never sold, use product creation date as proxy
   • Age = today - last_sold_date
   • Assign to aging bucket

5. OPERATION: inventoryItems — query Inputs: Inventory item IDs for cost data Expected output: Unit costs for value calculation

6. Calculate per bucket:

   • Total units
   • Total value (units × unitCost)
   • Monthly carrying cost = (value × carrying_cost_pct / 100) / 12
   • % of total inventory value

GraphQL Operations

# productVariants:query — validated against api_version 2025-01
query VariantsWithStock($query: String, $after: String) {
  productVariants(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        sku
        inventoryQuantity
        product { id title vendor status createdAt }
        inventoryItem {
          id
          unitCost { amount currencyCode }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

# orders:query — validated against api_version 2025-01
query RecentSales($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        createdAt
        lineItems(first: 50) {
          edges {
            node {
              quantity
              variant { id }
            }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

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

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Inventory Aging Report               ║
║  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>

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
INVENTORY AGING REPORT
  Total SKUs with stock:  <n>
  Total inventory value:  $<amount>
  ─────────────────────────────
  AGING BUCKETS:
  0-30 days:    <n> SKUs  $<value> (<pct>%)  ✅ Fresh
  31-60 days:   <n> SKUs  $<value> (<pct>%)  ⚠️ Watch
  61-90 days:   <n> SKUs  $<value> (<pct>%)  ⚠️ Aging
  91-180 days:  <n> SKUs  $<value> (<pct>%)  🔴 Stale
  181+ days:    <n> SKUs  $<value> (<pct>%)  🔴 Dead

  Monthly carrying cost: $<amount>
  Annual carrying cost:  $<amount>

  Top aging items by value:
    "<product>" SKU:<sku>  Age:<n>d  Qty:<n>  Value:$<n>

  Output: inventory_aging_<date>.csv
══════════════════════════════════════════════

Output Format

CSV file inventory_aging_<YYYY-MM-DD>.csv with columns: variant_id, sku, product_title, vendor, quantity, unit_cost, total_value, last_sold_date, age_days, aging_bucket, monthly_carrying_cost

Error Handling

Best Practices

• Use carrying_cost_pct: 25 as default (includes storage, insurance, opportunity cost, shrinkage).
• Items in 90+ day buckets are strong candidates for markdowns — use bulk-price-adjustment.
• Cross-reference with dead-stock-identifier and stock-velocity-report for a complete inventory health picture.
• Run monthly to track aging trends and measure liquidation effectiveness.