用途
该技能用于批量更新 Shopify 订单上已有履约（fulfillment）的物流跟踪号和承运商 URL。适用于承运商在标签重印后重新签发跟踪 ID、3PL 批量上传修正后的跟踪号，或承运商集成推送了错误跟踪号等场景。它替代了在 Shopify 后台逐单手动修正跟踪信息的做法。
主要能力
- 按订单查询现有履约信息，确认履约 ID 与跟踪信息匹配。
- 通过 fulfillmentUpdate 变更批量更新跟踪号、承运商和 URL。
- 可选是否向客户重发发货确认通知（notify_customer）。
- 支持 dry_run 预览，在提交前确认履约列表。
- 输出 CSV 结果文件，记录订单名、履约 ID、新旧跟踪号、承运商、通知状态和处理状态。
- 支持 human 或 json 两种输出格式。
使用方式
前置条件：
- 已认证的 Shopify CLI 会话：
shopify store auth --store <domain> --scopes read_orders,write_fulfillments - API 权限范围：read_orders、write_fulfillments
参数：
- store（string，必填）：店铺域名，例如 mystore.myshopify.com
- updates（array，必填）：由 {order_id, fulfillment_id, tracking_number, tracking_url, carrier} 对象组成的列表
- notify_customer（bool，可选，默认 false）：是否重发包含更新后跟踪信息的发货确认
- dry_run（bool，可选，默认 true）：预览更新而不执行变更
- format（string，可选，默认 human）：输出格式，human 或 json
工作流程：
- order 查询：对 updates 中每个订单，以 id: <order_id> 查询，返回 Order 及其 fulfillments { id, trackingInfo }，确认现有履约 ID 匹配。
- fulfillmentUpdate 变更：输入 fulfillmentId、trackingInfoUpdateInput: { company, number, url } 和 notifyCustomer，返回 fulfillment { id, trackingInfo } 与 userErrors。
GraphQL 操作（针对 api_version 2025-01 验证）：
# order:query
query OrderFulfillments($id: ID!) {
order(id: $id) {
id
name
fulfillments {
id
status
trackingInfo {
company
number
url
}
}
}
}
# fulfillmentUpdate:mutation
mutation FulfillmentUpdate($fulfillmentId: ID!, $trackingInfoInput: FulfillmentTrackingInput!, $notifyCustomer: Boolean) {
fulfillmentUpdate(
fulfillmentId: $fulfillmentId
trackingInfoUpdateInput: $trackingInfoInput
notifyCustomer: $notifyCustomer
) {
fulfillment {
id
status
trackingInfo {
company
number
url
}
}
userErrors {
field
message
}
}
}
会话跟踪：技能要求在每阶段输出固定格式信息。开始时输出带技能名、店铺域名和开始时间的横幅；每步后输出 [N/TOTAL] 查询/变更、操作名、参数摘要和结果；dry_run 为 true 时每个变更步骤前加 [DRY RUN] 且不执行；完成时按 human 或 json 格式输出结果摘要。
输出格式：CSV 文件 tracking_update_<YYYY-MM-DD>.csv，列为 order_name, fulfillment_id, old_tracking_number, new_tracking_number, carrier, notify_customer, status。
适用场景
- 承运商重新分配跟踪 ID 后的批量修正。
- 3PL 批量上传修正后的跟踪号。
- 承运商集成推送了错误跟踪号时的纠正。
限制与安全
- fulfillmentUpdate 会覆盖现有跟踪信息。
- 除非明确需要重发发货通知，否则应设置 notify_customer: false；若启用，每个被更新的履约都会向客户发送新邮件。
- 建议先用 dry_run: true 确认履约列表后再提交。
- 错误处理：THROTTLED（API 速率超限）等待 2 秒并最多重试 3 次；fulfillmentUpdate 的 userErrors（履约已取消或未找到）记录错误、跳过并继续；履约 ID 不在订单上（updates 列表中 ID 过期）记录不匹配、跳过并继续。
- 最佳实践：尽可能在 updates 输入中直接提供 fulfillment_id 以跳过订单查询步骤；对于通过 CSV 发送修正跟踪号的 3PL 集成，先解析 CSV 为 updates 数组再运行。