address-correction

用途在未发货订单上更正收货地址，无需通过 Shopify 后台界面操作。当客户下单后提交更正（例如街道地址拼写错误或邮编错误）时，此技能会通过 Admin API 直接执行地址更新，替代 Shopify 后台的手动地址编辑流程。更新必须在订单发货前完成；如果订单已发货或部分发货，技能将中止并报错。一旦开始发货，就无法再通过此技能更新 Shopify 订单记录。

前置条件

已认证的 Shopify CLI 会话：shopify auth login --store <domain>
API 权限范围：read_orders、write_orders

参数

store（string，必填）：店铺域名（例如 mystore.myshopify.com）
format（string，选填，默认 human）：输出格式，human 或 json
dry_run（bool，选填，默认 false）：预览操作而不执行变更
order_id（string，必填）：订单的 GID（例如 gid://shopify/Order/12345）
new_address（object，必填）：新的收货地址，包含 address1、address2（可选）、city、province、country、zip、phone（可选）、first_name、last_name

安全说明第 2 步会执行 orderUpdate，立即更改记录中的收货地址。如果订单已交给履约合作方，需要另行通知对方——此技能只更新 Shopify 记录。如果 displayFulfillmentStatus 不是 UNFULFILLED，技能将中止并报错。无法对部分发货或已发货订单应用地址变更。

工作流程步骤

OPERATION: order — 查询输入：id: <order_id> 预期输出：订单名称、displayFulfillmentStatus、当前 shippingAddress；如果 displayFulfillmentStatus != "UNFULFILLED"，则中止并输出消息："Cannot update address: order has already been fulfilled."
OPERATION: orderUpdate — 变更输入：input.id: <order_id>、input.shippingAddress: <new_address object> 预期输出：订单上更新后的 shippingAddress、userErrors

GraphQL 操作

# order:query — validated against api_version 2025-01
query OrderForAddressCheck($id: ID!) {
  order(id: $id) {
    id
    name
    displayFulfillmentStatus
    shippingAddress {
      address1
      address2
      city
      province
      country
      zip
      phone
      firstName
      lastName
    }
  }
}

# orderUpdate:mutation — validated against api_version 2025-01
mutation OrderUpdate($input: OrderInput!) {
  orderUpdate(input: $input) {
    order {
      id
      shippingAddress {
        address1
        address2
        city
        province
        country
        zip
        phone
      }
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪在每个阶段必须输出指定内容。开始时输出带 SKILL、Store、Started 信息的方框；每一步之后输出 [N/TOTAL] 形式的过程信息（含操作类型、名称、参数摘要和结果摘要）；如果 dry_run 为 true，每个变更步骤前加 [DRY RUN] 前缀且不执行；完成时按 format 输出：human（默认）输出 OUTCOME SUMMARY 摘要，json 则输出包含 skill、store、started_at、completed_at、dry_run、steps 和 outcome 的 JSON 对象。

输出格式无 CSV 输出。技能会在会话完成摘要中报告更新后的地址，新地址显示在 [2/2] 步骤输出中。

错误处理

displayFulfillmentStatus != UNFULFILLED：订单已发货或部分发货。恢复方式：无法更新地址，需直接联系承运商。
orderUpdate 返回 userErrors：地址字段无效（例如无效的国家代码）。恢复方式：核对 ISO 国家代码及省/州格式。
Order not found：订单 GID 无效。恢复方式：使用 order-lookup-and-summary 技能查找正确的订单 ID。

最佳实践

始终先运行 dry_run: true——第 1 步会展示当前地址以供确认，然后再由第 2 步提交更改。
country 必须使用 ISO 3166-1 alpha-2 代码（例如 US、CA、GB），而不是完整国家名称。
此技能只更新 Shopify 订单记录。如果使用第三方履约服务商，还需在其系统中更新地址。
phone 字段使用 E.164 格式（例如 +15551234567）。
更新后，使用 order-lookup-and-summary 技能确认地址更改已生效。

技能介绍