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

安全性

该技能为只读技能，不执行任何变更操作，可随时安全运行。

工作流程

OPERATION: orders — query
- 输入：query: "financial_status:paid created_at:>='<NOW - days_back days>'", first: 250, select shippingLines { title, discountedPriceSet, originalPriceSet, carrierIdentifier }, pagination cursor
- 预期输出：包含运输行详情的订单；分页直到 hasNextPage: false
对每条运输行：记录承运商（来自 title 或 carrierIdentifier）、收取金额（discountedPriceSet）以及实际成本（如有）。
按承运商/方式分组；计算总收取金额、总成本、净补贴/超额。

GraphQL 操作

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

会话跟踪

Claude 必须在每个阶段输出以下内容，此为强制要求。

开始运行时输出：

╔══════════════════════════════════════════════╗ ║ 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 搭配使用，评估免运费门槛是否带来了预期的 AOV 提升。
如需对实际承运商成本进行对账，请与承运商发票交叉核对——Shopify 的 API 仅存储向客户收取的金额，除非您的承运商集成将实际支付给承运商的成本回写，否则不存储实际支付成本。