Shopify API 2026-10 RC 迁移清单：订阅、订单、库存与 Checkout

先划清阶段：RC 用于开发测试，10月1日才转为 stable

2026年9月22日核查时，Shopify 的 2026-10 release notes 列出订单、Metafield、Customer Account、税务和运费等变更，并将该版本标为 Release Candidate。页面明确说明它在10月1日前供开发测试，之后才转为 stable；因此现在应该做兼容性验证，而不是把所有生产店写成已经切换。

各项变更有自己的原始公告日期，例如 priceRule 是6月23日、Carrier Service 是6月26日、Customer Account Checkout 是7月6日、Metafield filter 是7月24日、订单地址税费是7月30日。不要把聚合页时间轴显示的日期当作 RC 首发日或每项功能第一次公布的日期；逐项时间应以对应 changelog 为准。

订单地址与税费：更新成功后必须重读财务字段

从 API 2026-10 起，通过 orderUpdate 或 REST Admin order update 修改完全未履约订单的收货地址，会按新目的地重算税费。应用随后应重读 taxLines、totalTaxSet、订单总额和余额，而不是继续使用更新前缓存。已付款订单可能出现应补或应退差额，处理方式必须服从商家自己的容差与财务流程。

三个边界不能省略：2026-10以前的请求只改地址、不重算税；部分或全部履约订单不重算；不可编辑订单也不重算。一个可复核场景是：在开发店建立完全未履约订单，记录税费与余额，跨税区改地址后比较字段，再分别用部分履约夹具确认没有误重算。这个场景是测试设计，不是已观察到的客户事故。

订阅合约：从有状态 Draft 迁移到 calculate、poll、review、commit

SubscriptionContractCalculation 是 SubscriptionDraft 的后继方案，但 RC 阶段两者仍会并存。需要创建、更新或编辑订阅合约的应用，应按具体操作调用 subscriptionContractCreateCalculate、subscriptionContractUpdateCalculate 或 subscriptionBillingCycleContractEditCalculate；只读合约，或只使用 subscriptionContractActivate、subscriptionContractPause 等状态 mutation 的应用，不需要为了这项变更重写。不要把“后继方案”误读成 2026-10 立即删除旧 API。

calculate 返回 SubscriptionContractCalculationPending 后，应用可轮询 subscriptionContractCalculation，或订阅 subscription_contract_calculations/succeed 与 subscription_contract_calculations/fail。成功后先复核计算后的合约、totals、warnings 与 errors，再调用 subscriptionContractCalculationCommit；Webhook 到达不会自动 commit。输入校验若直接返回 user error，应先修正输入，因为这时不会创建异步 calculation。失败 calculation 有 errors；被 Shopify void 的失败可能没有 errors，官方文档建议重试。

迁移测试至少覆盖三条路径：成功 calculation 经人工或规则复核后 commit；输入 user error 不进入轮询；fail/voided 在有无 errors 时分别停止或有限重试。commit 会生成新的 contract version，但不会修改既有 orders 或 fulfillments。若轮询超时、结果差异无法解释、Webhook 与查询状态不一致，或新旧账单金额不能对齐，应停止升级并保留旧版本路径。

Schema 穷举项：错误码、履约枚举、换货字段与 Metafield

InventoryAdjustQuantities、InventoryMoveQuantities、InventorySetOnHandQuantities 与 InventorySetQuantitiesUserErrorCode 移除 ITEM_NOT_STOCKED_AT_LOCATION；依赖该分支的错误映射、告警、fixture 与生成枚举需要删除或改写。Order.displayFulfillmentStatus 等 OrderDisplayFulfillmentStatus 字段新增 FULFILLMENT_NOT_REQUIRED：当订单剩余可履约数量为0时，它取代 UNFULFILLED。所有穷举 switch、报表映射和前端标签都应加入新值测试。

ExchangeLineItem 新增 productId、title、variantSku、variantTitle。只有需要换货行商品身份或展示快照的应用才应请求这些字段；先更新查询、生成类型、权限审查和空值 fixture，再确认旧客户端不会因响应选择集或本地 schema snapshot 失败。

draftOrderCalculate、draftOrderCreate、draftOrderUpdate 返回的 DraftOrderDiscountNotAppliedWarning 不再提供 priceRule；应用应改读 discountTitle 和 discountCode。由于该字段是公开 schema 中 PriceRule 的最后可达入口，相关遗留类型也会移除。要同时搜索查询文本、fragment、生成类型、schema snapshot、mock 与 fixture。

Metafield filter 在定义不存在、未启用 filtering、字段类型或比较操作不支持时会直接返回错误，不再静默忽略谓词。迁移时逐条确认 definition、filtering 配置与 comparison，针对合法、无效和空结果三类查询建立夹具；不要把 GraphQL error 吞掉后返回空列表，否则会把配置错误伪装成没有数据。

Customer Account 与税务 payload：不是简单改字段名

Customer Account API 的 Customer.lastIncompleteCheckout 以及 Checkout、AppliedGiftCard、AvailableShippingRates、CheckoutLineItem、ShippingRate 等不可达子树被删除，而且官方明确说没有 Customer Account API 替代。仍依赖该查询的应用要删除引用；若产品确实需要活跃购物状态，应另行评估 Storefront cart flow，不能假装存在一对一替代字段。

第三方税务集成还要检查 tax calculation request 与 tax summary webhook。实体引用改为 gid://shopify/... 形式，并增加顶层 admin_graphql_api_id 类字段。ID 解析、持久化键、Webhook fixture、重放工具和日志脱敏规则都要一起验证；不能只在类型定义里把整数改成字符串就宣布完成。

Carrier Service：注册成功不等于结账已有费率

2026-10 的 carrierServiceCreate 和对应 REST 创建接口只注册服务，不再自动把费率加入 General shipping profile。创建请求成功后，应用或商家仍需在适用 shipping profile 与 zone 中配置 carrier-calculated rates，并用代表性地址确认结账可见。

迁移测试应区分服务对象存在、profile 关联存在、zone 覆盖正确和 checkout 实际返回费率四层。不要把创建接口的成功响应当作完整上线验证，也不要把官方仅对 create 的说明外推为所有 update 行为都已得到同样保证。

一套可执行的迁移顺序

第一步，按依赖做代码与配置清点：订阅合约编辑、库存错误码、履约枚举、换货行、订单地址更新、DraftOrder warning、Metafield filter、Customer Account Checkout、税务 payload 与 Carrier Service。第二步，在 2026-10 schema 下重生成类型，让已删除字段和新增枚举在编译或测试阶段暴露。第三步，准备 calculation 成败、库存错误、零剩余履约、换货空值、税区变化、无效 filter、GID payload 与运费 profile 夹具。

第四步，在开发店或隔离环境比较旧版本与 2026-10 的请求、异步状态、响应、错误、余额和结账结果。第五步，记录每个失败的责任层、停止条件和回退版本。Customer.createdAt、ShopifyQL app analytics 与 Storefront @inContext(channelId) 也是该 RC 的独立新增能力，但不属于订阅、订单或库存迁移的必改链；只有实际使用时才评估。

验证、停止与回退边界

通过标准至少包括：生成类型无已删除引用；subscription calculation 成功、失败与 voided 路径可区分且不会误 commit；新错误码与履约枚举映射完整；ExchangeLineItem 新字段有空值夹具；订单税费与余额差异能解释；无效 Metafield filter 明确报错；Customer Account 删除子树不再被请求；税务 GID 能解析；Carrier Service 的 profile、zone 与 checkout 费率均可验证。

若 calculation 长时间 pending、fail/voided 处理不确定、commit 前差异无法解释、账务差额无法解释、Webhook 解析丢失实体、结账不显示预期费率，或回退会破坏已迁移数据，应停止版本升级。RC 期间可回到仍受支持且已验证的旧版本争取修复时间，但不能把旧版本当永久方案。若 Shopify 在10月1日前调整 RC，必须复查原 URL 并更新同一页面。