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

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store | string | yes | — | Store domain (e.g., mystore.myshopify.com) | | days_back | integer | no | 30 | Lookback window | | format | string | no | human | Output format: human or json |

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:>=''", first: 250, select shippingLines { title, discountedPriceSet, originalPriceSet, carrierIdentifier }, pagination cursor Expected output: Orders with shipping line details; paginate until hasNextPage: false

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

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

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:                        ║
║  Started:              ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL]   
          → Params: 
          → Result: 

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
SHIPPING COST ANALYSIS  ( days)
  Orders analyzed:     
  Total charged to customers: $
  Free shipping orders:       

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

For format: json, emit:

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

Output Format

CSV file shipping_cost_.csv with columns: order_name, shipping_method, carrier, charged_amount, original_price, discount_applied, currency

Error Handling

| Error | Cause | Recovery | |-------|-------|----------| | THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times | | No shipping lines | Digital products or free shipping store | Report $0 shipping revenue | | Carrier identifier missing | Custom or manual shipping methods | Use title as carrier name |

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 40RTY-ai
• Source: 40RTY-ai/shopify-admin-skills
• License: MIT
• Homepage: http://skills.40rty.ai

Install and usage instructions live in the source repository linked above.