Shopify Admin 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

• Authenticated Shopify CLI session: shopify store auth --store <domain> --scopes read_orders
• API scopes: read_orders
• Actual shipping costs are only available if recorded via the Shopify Admin API or carrier-calculated shipping; manually entered orders may lack cost data.

Parameters

Safety

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

Workflow Steps

1. OPERATION: orders — query Inputs: query: "financial_status:paid created_at:>='<NOW - days_back days>'", first: 250, select shippingLines { title, discountedPriceSet, originalPriceSet, carrierIdentifier }, pagination cursor Expected output: Orders with shipping line details; paginate until hasNextPage: false

2. For each shipping line: record carrier (from title or carrierIdentifier), charged amount (discountedPriceSet), and actual cost if available

3. Group by carrier/method; calculate total charged, total cost, net subsidy/overage

GraphQL Operations

graphqlCopy code
# 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:

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

jsonCopy code
{
  "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_<YYYY-MM-DD>.csv with columns: order_name, shipping_method, carrier, charged_amount, original_price, discount_applied, currency

Error Handling

Best Practices

• Free shipping orders show $0 charged but the actual carrier cost is your subsidy — knowing this per carrier helps evaluate free shipping threshold decisions.
• originalPriceSet vs discountedPriceSet difference represents shipping discounts applied to customers — useful for understanding total shipping subsidy cost.
• Pair with average-order-value-trends to evaluate whether free shipping thresholds are driving the intended AOV lift.
• For actual carrier cost reconciliation, cross-reference with carrier invoices — Shopify's API only stores what was charged to customers, not what was paid to carriers unless your carrier integration writes those costs back.