shipping-cost-analysis

用途

按承运商与配送方式，比较向客户收取的运费金额与订单上记录的实际运费成本，从而找出运费被补贴（收取金额低于成本）或被多收的环节。该技能为只读操作，不执行任何写操作。

前提条件

已认证的 Shopify CLI 会话：

shopify store auth --store <domain> --scopes read_orders

API 权限范围：read_orders
实际运费成本只有在通过 Shopify Admin API 记录，或使用承运商实时计算运费时才可用；手动录入的订单可能缺少成本数据。

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	30	回溯窗口
format	string	否	human	输出格式：human 或 json

安全性

只读技能，不执行任何写操作，可随时安全运行。

工作流程

操作：orders — 查询
- 输入：query: "financial_status:paid created_at:>='<NOW - days_back days>'", first: 250, select shippingLines { title, discountedPriceSet, originalPriceSet, carrierIdentifier }, 分页游标
- 预期输出：包含运费明细的订单；持续分页直到 hasNextPage: false
对每条运费明细：记录承运商（来自 title 或 carrierIdentifier）、收取金额（discountedPriceSet），以及（若可用）实际成本
按承运商／配送方式分组；计算总收取金额、总成本、净补贴／超额

GraphQL 操作

# orders:query — 已针对 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
    }
  }
}

会话跟踪

工具必须在每个阶段输出以下信息，这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Shipping Cost Analysis               ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

每个步骤后输出：

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

完成时输出。

format 为 human（默认）时：

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

format 为 json 时：

{
  "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"
}

输出格式

生成 CSV 文件 shipping_cost_<YYYY-MM-DD>.csv，列包含：order_name, shipping_method, carrier, charged_amount, original_price, discount_applied, currency。

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
No shipping lines	数字产品或免运费店铺	报告运费收入为 $0
Carrier identifier missing	自定义或手动配送方式	使用 title 作为承运商名称

最佳实践

免运费订单显示收取金额为 $0，但实际承运成本就是你的补贴；按承运商了解这一点，有助于评估免运费门槛决策。
originalPriceSet 与 discountedPriceSet 的差值代表给予客户的运费折扣，有助于理解总的运费补贴成本。
可与 average-order-value-trends 配合使用，评估免运费门槛是否带来了预期的平均订单价值提升。
若需核对实际承运成本，请与承运商发票交叉比对——Shopify 的 API 只存储向客户收取的金额，不存储向承运商支付的金额，除非你的承运商集成回写了这些成本。