Shipping Cost Analysis

Purpose

Compares the shipping amount charged to customers against the actual shipping cost recorded on orders, broken down by carrier and shipping method. Identifies where shipping is being subsidized (charged less than cost) or over-charged. Read-only — no mutations.

Prerequisites

Parameters

Safety

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

Workflow Steps

Inputs: query: "financial_status:paid created_at:>=''", first: 250, select shippingLines { title, discountedPriceSet, originalPriceSet, carrierIdentifier }, pagination cursor

Expected output: Orders with shipping line details; paginate until hasNextPage: false

GraphQL Operations

# orders:query — validated against api_version 2025-01
query ShippingCostAnalysis($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        totalShippingPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        shippingLines(first: 5) {
          edges {
            node {
              id
              title
              carrierIdentifier
              originalPriceSet {
                shopMoney {
                  amount
                  currencyCode
                }
              }
              discountedPriceSet {
                shopMoney {
                  amount
                  currencyCode
                }
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Session Tracking

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

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Shipping Cost Analysis               ║
║  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):

══════════════════════════════════════════════
SHIPPING COST ANALYSIS  (<days_back> days)
  Orders analyzed:     <n>
  Total charged to customers: $<amount>
  Free shipping orders:       <n>

  By Carrier/Method:
    "Standard Shipping"  Orders: <n>  Charged: $<n>  Avg: $<n>
    "Express"            Orders: <n>  Charged: $<n>  Avg: $<n>
  Output: shipping_cost_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "shipping-cost-analysis",
  "store": "<domain>",
  "period_days": 30,
  "orders_analyzed": 0,
  "total_shipping_charged": 0,
  "free_shipping_order_count": 0,
  "currency": "USD",
  "by_method": [],
  "output_file": "shipping_cost_<date>.csv"
}

Output Format

CSV file shipping_cost_.csv with columns:

order_name, shipping_method, carrier, charged_amount, original_price, discount_applied, currency

Error Handling

Best Practices