tracking-update-bulk

用途

该技能用于查找订单上已有的履约记录，并批量更新其物流跟踪号和承运商 URL。适用于以下场景：承运商在重新打印面单后重新分配跟踪 ID、第三方物流（3PL）批量上传更正后的跟踪信息，或承运商集成推送了错误的跟踪号。它可替代在 Shopify 后台逐单手动更正跟踪信息的操作。

前置条件

已认证的 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

安全提示

⚠️ fulfillmentUpdate 会覆盖已有的跟踪信息。除非你明确希望重新发送发货通知，否则请设置 notify_customer: false——若启用，客户会为每个被更新的履约收到一封新邮件。提交前请先以 dry_run: true 运行，确认履约列表。

工作流程步骤

OPERATION: order — query
- 输入：对 updates 中的每个订单使用 id: <order_id>
- 预期输出：包含 fulfillments { id, trackingInfo } 的 Order，用于确认已有履约 ID 是否匹配
OPERATION: fulfillmentUpdate — mutation
- 输入：fulfillmentId: <id>、trackingInfoUpdateInput: { company, number, url }、notifyCustomer
- 预期输出：fulfillment { id, trackingInfo }、userErrors

GraphQL 操作

# order:query — validated against api_version 2025-01
query OrderFulfillments($id: ID!) {
  order(id: $id) {
    id
    name
    fulfillments {
      id
      status
      trackingInfo {
        company
        number
        url
      }
    }
  }
}

# fulfillmentUpdate:mutation — validated against api_version 2025-01
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
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Tracking Update Bulk                 ║
║  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>

若 dry_run: true，为每个 mutation 步骤添加 [DRY RUN] 前缀，且不执行该步骤。

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Fulfillments targeted:   <n>
  Tracking numbers updated: <n>
  Notifications sent:       <n>
  Errors:                   <n>
  Output:                   tracking_update_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "tracking-update-bulk",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": true,
  "outcome": {
    "targeted": 0,
    "updated": 0,
    "notifications_sent": 0,
    "errors": 0,
    "output_file": "tracking_update_<date>.csv"
  }
}

输出格式

CSV 文件 tracking_update_<YYYY-MM-DD>.csv，包含列： order_name, fulfillment_id, old_tracking_number, new_tracking_number, carrier, notify_customer, status

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
fulfillmentUpdate 上的 userErrors	履约已取消或未找到	记录错误，跳过，继续
履约 ID 不在订单上	updates 列表中的 ID 已过期	记录不匹配，跳过，继续

最佳实践

除非承运商正在跟踪替换发货，否则保持 notify_customer: false——客户会觉得重复的发货邮件令人困惑，并可能因此开启不必要的支持工单。
尽可能在 updates 输入中直接提供 fulfillment_id，以完全跳过订单查找步骤。
对于通过 CSV 发送更正后跟踪信息的 3PL 集成，在运行此技能前先将 CSV 解析为 updates 数组。