服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务,不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动,严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外,不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- 影响升到 2027-01 或更新版本、并且在 REST Gift Card 写请求里发送 line_item_id 的应用。
- 创建、替换或清空订单行关联的请求值都会被忽略。已有的订单行和订单关联仍可读取。
- 迁移时同时检查请求构造和写后同步。升级前用开发环境回读同一张测试卡,避免本地记录保留被忽略的值。
什么时候会遇到只读行为?
Shopify 在 2026 年 10 月 30 日公布这项变更。它针对 REST Admin API 2027-01 及之后版本的 Gift Card 创建和更新。只读取该字段的代码可以保留,更早 API 版本按其原有行为处理。
2027-01 目前在 Shopify 版本表标为候选版,稳定版日期列为 2027 年 1 月 1 日。准备升级时,先检查请求使用的版本和响应头 X-Shopify-API-Version。所选版本不可用时,Shopify 可能按默认可用版本处理。
成功响应之后,如何判断关联是否变化?
line_item_id 表示 Shopify 发出礼品卡时关联的订单行。请求里带这个字段时,Shopify 仍可正常处理请求中的其他字段,但传入的关联值不会生效。
例如,假设某张测试卡已经关联订单行 A。更新时如果请求带订单行 B,即使其他字段更新成功,订单行关联仍是 A。同步程序若直接拿请求中的 B 更新本地记录,就会和 Shopify 的响应不同。
应用里要改哪些读写路径?
检查礼品卡创建、更新及重试时组装的请求体,找出 line_item_id 的来源。还要留意是否直接把 GET 返回的整张卡复制成更新请求。写入时用该版本实际允许的字段构造请求。
响应模型和报表仍可读取已有订单行与订单关联。回写本地记录时,按 Shopify 实际响应或回读值更新。Shopify 写明,没有供外部应用新增、替换或清空这项关联的替代 API。
读写权限需要重新申请吗?
Shopify 的 Gift Card 参考文档仍要求礼品卡访问权限,并指引开发者向 Shopify Support 申请 read_gift_cards 与 write_gift_cards。先核对现有应用获批的 scope。字段只读公告没有说明要重新申请现有权限,也没有扩大写入范围。
排查迁移后的差异时,把版本、接口权限和响应里的关联分开核实。确认请求具有所需访问权限后,再判断关联是否真正变化。
切换前怎么验证?
在获准的开发店铺用合成数据测试。对一张已有订单行关联的测试卡,先留存原关联。移除请求字段后,发起一次允许的更新,再读取同一张卡,核对关联与更新前一致。
创建流程也应验证省略该字段时的行为。检查响应中的 API 版本和实际关联,再核对测试记录是否采用了响应值。日志保留版本和字段结果即可,避免写入完整礼品卡兑换码。
资料来源
常见问题
传 null 或空字符串能清除现有关联吗?
从 2027-01 起,创建或更新请求中的 line_item_id 都会被忽略。传空值也不会清除现有订单行。
为什么从请求类型里删掉字段后,读取类型还需要它?
只读字段仍可随 Gift Card 响应返回。读取和写入使用各自的字段定义,报表需要核对现有关联时可保留读取字段。