Shopify API 2026-10 稳定版迁移清单：订阅、订单与 Checkout

2026-10 已稳定，先确认应用实际使用的版本

Shopify 当前版本说明将2026-10列为最新稳定版，发布日期为2026年10月1日；2027-01列为候选版。2026-10已可用于生产，候选版仍可能出现不兼容调整。应用应明确选择版本，再按自己的发布流程验证升级。

本清单针对订阅合约编辑、订单地址、库存与履约映射、Metafield 查询、Customer Account 和运费集成。新版本包含其他能力，不要求每个应用全部采用。各项变更的公告日也不同，不能把聚合页当前日期当成功能首次发布日。

订单地址变化后，重读税费、总额和余额

从2026-10起，通过 orderUpdate 或 REST Admin API 更新完全未履约订单的收货地址，会按新目的地重算税费。修改后重新查询 taxLines、totalTaxSet、订单总额和余额；已付款订单也可能出现应补或应退差额，应按商家自己的财务流程处理。

这条规则有三个边界：早于2026-10的请求保留原税费；部分或全部履约的订单不重算；不符合订单编辑条件的订单也不重算。可在开发店设计跨税区改地址的用例，并分别覆盖完全未履约、部分履约和不可编辑订单。

订阅编辑需要计算、等待、复核，再提交

SubscriptionContractCalculation 是 SubscriptionDraft 的后继方案。当前说明仍保留旧 Draft API，但新能力需要计算 API；只读合约，或只调用 subscriptionContractActivate、subscriptionContractPause 等状态操作的应用，不受这条编辑流程迁移影响。

创建、更新和账单周期编辑分别使用 subscriptionContractCreateCalculate、subscriptionContractUpdateCalculate、subscriptionBillingCycleContractEditCalculate。收到 SubscriptionContractCalculationPending 后，轮询 subscriptionContractCalculation，或等待 subscription_contract_calculations/succeed、subscription_contract_calculations/fail。先复核完整计算结果、金额、warnings 和 errors，再调用 subscriptionContractCalculationCommit。Webhook 本身不会提交计算结果。

输入 user error 不会创建异步 calculation，应先修正输入。提交成功会产生新的合约版本，不会修改已创建的订单或履约记录。采用前还要核对 read_own_subscription_contracts、write_own_subscription_contracts 及所需订阅 API 访问资格；在 Shopify 后台直接创建的 custom app 不能使用该订阅能力，单店方案应按官方指引在 Dev Dashboard 创建应用。

Schema 与查询：找出删除字段和新增分支

库存数量相关的 InventoryAdjustQuantities、InventoryMoveQuantities、InventorySetOnHandQuantities 及 InventorySetQuantitiesUserErrorCode 移除 ITEM_NOT_STOCKED_AT_LOCATION。OrderDisplayFulfillmentStatus 增加 FULFILLMENT_NOT_REQUIRED：剩余可履约数量为0时可能返回该值。同步检查生成类型、穷举分支、报表和用户界面标签。

DraftOrderDiscountNotAppliedWarning 删除 priceRule，改读 discountTitle 和 discountCode；公开 schema 中的遗留 PriceRule 及相关类型也被移除。搜索 draftOrderCalculate、draftOrderCreate、draftOrderUpdate 的查询、fragment 和夹具。ExchangeLineItem 的 productId、title、variantSku、variantTitle 是可按需求采用的新增字段。

无效 Metafield filter 现在返回错误，不再忽略错误谓词。逐条确认 metafield definition 存在、允许 filtering，且字段类型支持使用的比较操作。分别验证合法查询、无效查询和合法的空结果，避免把 GraphQL error 当作“没有数据”。

Customer Account 的旧 Checkout 查询没有直接替代

Customer Account API 移除 Customer.lastIncompleteCheckout 及不可达的 Checkout 类型子树。升级前移除这些字段引用；官方没有给出同一个 API 内的替代字段。

若业务仍需购物车或结账状态，应单独评估 Storefront cart 流程的适用性、权限和数据映射。它需要产品与集成设计，不能仅替换字段名就视为迁移完成。

Carrier Service 创建成功后，还要配置结账费率

2026-10 的 carrierServiceCreate 和对应 REST 创建接口只注册服务，不再自动把费率加入 General shipping profile。随后仍需在适用的 shipping profile 与 zone 中配置 carrier-calculated rates。

验证时分开确认服务对象、profile 关联、zone 覆盖和实际 checkout 费率。用代表性收货地址检查结果，不把创建接口成功响应当作结账已可用的证明；官方对 create 的说明也不能直接外推为所有 update 行为。

按依赖迁移，保留可解释的停止与回退条件

先盘点实际依赖，再按2026-10 schema 更新查询与生成类型。为订阅计算成败、零剩余履约、税区变化、无效 filter、已删除 Checkout 字段及运费配置准备开发店或隔离环境用例。

比较旧版本与2026-10的响应、异步状态、错误、金额和结账结果。计算结果尚未复核、金额差异无法解释、Webhook 与查询不一致，或预期运费未出现时，应停止扩大升级范围并保存问题证据。

回退只能使用仍可访问且已经验证的版本，并核对已写入数据是否兼容。不要依赖已失效版本名维持旧行为；版本回退也不能替代对已产生订单、合约或财务差异的处理。