Inventory Aging Report

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

Parameters

Safety

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

Workflow Steps

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

Inputs: query: "created_at:>=''", first: 250, select createdAt, lineItems { variant { id }, quantity }, pagination cursor

Expected output: Sales history to determine last-sold date per variant

Inputs: Inventory item IDs for cost data

Expected output: Unit costs for value calculation

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_.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