Average Order Value Trends

Purpose

Calculates Average Order Value (AOV) over configurable time buckets (daily, weekly, monthly) and segments results by new vs. returning customers. Tracks AOV trends to measure the impact of upsell programs, bundle offers, or free shipping thresholds. Read-only — no mutations.

Prerequisites

Parameters

Safety

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

Workflow Steps

Inputs: query: "created_at:>=''", first: 250, select totalPriceSet, customer { id, numberOfOrders }, createdAt, pagination cursor

Expected output: All orders in window; paginate until hasNextPage: false

Inputs: Recent customers for new vs. repeat segmentation validation

GraphQL Operations

# orders:query — validated against api_version 2025-01
query AOVData($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          id
          numberOfOrders
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# customers:query — validated against api_version 2025-01
query NewVsReturningCustomers($query: String!, $after: String) {
  customers(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        numberOfOrders
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Average Order Value Trends           ║
║  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):

══════════════════════════════════════════════
AOV TRENDS  (<days_back> days, bucket: <bucket>)
  Orders analyzed:   <n>
  Overall AOV:       $<amount>
  New customer AOV:  $<amount>
  Returning AOV:     $<amount>

  Period      Orders   AOV     New AOV  Returning AOV
  ────────────────────────────────────────────────────
  2026-W14    <n>      $<n>    $<n>     $<n>
  Output: aov_trends_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "average-order-value-trends",
  "store": "<domain>",
  "period_days": 90,
  "overall_aov": 0,
  "new_customer_aov": 0,
  "returning_customer_aov": 0,
  "by_period": [],
  "output_file": "aov_trends_<date>.csv"
}

Output Format

CSV file aov_trends_.csv with columns:

period, order_count, aov, new_customer_orders, new_customer_aov, returning_orders, returning_aov, currency

Error Handling

Best Practices