Python调用Shopify REST API更新物流跟踪码异常问题咨询

API 探路者

2026-9-1

问题根因

2022-04及以上版本的Shopify Admin REST API已经重构了履约（Fulfillment）相关逻辑，400报错、履约状态停留在in progress、跟踪信息不展示的核心原因有三点：

调用的接口路径错误：当前使用的/admin/api/2022-04/orders/{orderID}/fulfillments.json是已废弃的旧版接口，已经不支持处理tracking_info等履约参数，即使返回201状态码，也只会创建空的待处理履约单，不会同步跟踪信息，也不会将订单标记为已履约，部分参数不兼容时直接返回400错误。
请求体格式不符合规范：tracking_urls字段要求传入数组类型，现有代码传入的是字符串，接口无法识别；缺少新接口强制要求的履约单ID、履约商品行参数，无法完成履约状态流转。
存在多余传参：新接口下location_id不需要手动传入，履约单（Fulfillment Order）生成时已经绑定对应库位，手动传入反而可能触发参数校验错误。

正确实现步骤

1. 拉取订单关联的有效履约单ID

新版履约接口必须基于订单自动生成的履约单ID创建，不能直接绑定订单ID创建，先调用订单详情接口拿到可用履约单和对应商品行信息：

import requests
from requests.structures import CaseInsensitiveDict

# 复用已配置好的鉴权headers
get_order_detail_url = f"{shop_url}/admin/api/2022-04/orders/{orderID}.json?fields=id,fulfillment_orders"
order_resp = requests.get(get_order_detail_url, headers=headers).json()

# 过滤出状态为open、可履约的履约单，排除已取消、已完成的条目
open_fulfillment_orders = [fo for fo in order_resp["order"]["fulfillment_orders"] if fo["status"] == "open"]
target_fo = open_fulfillment_orders[0]
# 提取该履约单下需要发货的商品行ID和可发货数量
fo_line_items = [
    {"id": item["id"], "quantity": item["fulfillable_quantity"]}
    for item in target_fo["line_items"]
]

2. 修正请求体结构

将tracking_urls改为数组格式，补充强制的line_items_by_fulfillment_order参数，移除多余的location_id、status字段：

payload = {
    "fulfillment": {
        "notify_customer": False,
        "tracking_info": {
            "tracking_number": f"{trackingCode}",
            "company": "DHL Express",
            # 注意该字段必须传数组，即使只有一个跟踪链接
            "tracking_urls": [f"https://对应物流商官方跟踪查询页地址?tracking-id={trackingCode}"]
        },
        "line_items_by_fulfillment_order": [
            {
                "fulfillment_order_id": target_fo["id"],
                "fulfillment_order_line_items": fo_line_items
            }
        ]
    }
}

3. 调用新版履约创建接口

新版接口的固定路径是/admin/api/2022-04/fulfillments.json，不需要在路径中拼接订单ID：

create_fulfillment_url = f"{shop_url}/admin/api/2022-04/fulfillments.json"
resp = requests.post(create_fulfillment_url, headers=headers, json=payload)
# 正常返回201状态码时，响应体中fulfillment的status为success，店铺端会自动同步承运商信息、物流跟踪码，订单状态更新为fulfilled
print(resp.status_code, resp.json())

注意事项

确认使用的自定义应用access_token已申请write_fulfillments、read_orders权限，否则会返回权限校验错误。
如果是分多个包裹发货，只需要在fulfillment_order_line_items中传入当前包裹对应的商品行ID和实际发货数量即可，不需要一次性履约单内所有商品。
如果使用的物流商不在Shopify内置物流商列表中，company字段直接传自定义物流商名称即可，不需要额外配置。

内容的提问来源于stack exchange，提问作者James Huang