在 POS UI 扩展 API 版本 2026-10 中，当 Shopify POS 未确认购物车已更改时，Cart API 的变更操作将拒绝执行；在早期版本中，无论 POS 是否应用了写入操作，这些变更操作都会解析成功。对于采用 2026-10 的应用而言，这是一项破坏性变更，这些应用在调用每次购物车变更时都需要处理被拒绝的承诺（rejected promise）。运行于 2026-07 及更早版本的应用不受影响。
变更内容
POS 会报告每次购物车写入操作的结果。只有成功结果才能确认购物车已发生变更。早期 API 版本无论结果如何都会解析该变更，因此应用无法区分已应用的写入和已丢弃的写入，并且可能在购物车未发生实际变更的情况下显示费用或折扣为已应用状态。
在 2026-10 中，除非 POS 确认写入操作，否则以下变更操作均会拒绝执行：bulkCartUpdate、removeLineItem、applyCartDiscount、addCartCodeDiscount、removeAllDiscounts、setCustomer、removeCustomer、addLineItemProperties、bulkAddLineItemProperties、removeLineItemProperties、setLineItemDiscount、bulkSetLineItemDiscounts、removeLineItemDiscount、addLineItemSellingPlan 和 removeLineItemSellingPlan。updateLineItemQuantity 是 2026-10 中新增的功能，并且从其首次发布起就会拒绝执行。
未确认的写入将抛出以下两种错误消息之一：
- POS refused the cart update. The cart was not changed. POS 拒绝了写入操作，购物车保持不变。这种情况可能发生在 POS 不再接受购物车变更时，例如收银员进入支付阶段后。一旦重新允许编辑购物车，重试可能会成功。
- POS could not confirm the cart update. 结果未知，可能存在部分写入的情况。在重试之前请先读取购物车数据。
上述两条消息涵盖了未确认写入的情况。购物车变更仍可能因其他原因被拒绝，例如无效的折扣值或缺少客户信息，因此仅在需要区分这两种情况时才对消息进行匹配。
受影响对象
从 POS UI 扩展中调用上述任何变更操作且使用 api_version = "2026-10" 或更高版本的应用程序需要注意：此变更按扩展程序应用，基于扩展程序声明的 API 版本，而非按商店应用。
运行于 2026-07 及更早版本的应用将继续保持当前行为，无需进行更改。已经使用 try/catch 包装购物车变更操作或附加 .catch() 处理程序的应用，将在写入操作未获确认时运行该处理程序，而不是像写入操作成功那样继续执行。
为何重要
目前，被丢弃的购物车写入操作是静默失败的。通过引入拒绝机制，这种静默的数据丢失将转化为调用方的错误，应用可以在此处进行重试、向员工展示提示信息或回滚自身状态。
破坏性变更与迁移指南
注意： 以前会解析成功的调用现在将拒绝执行。如果未捕获拒绝错误，则您的其余处理程序不会运行，包括在写入操作后渲染的任何用户界面以及清除加载状态等清理工作。
在将扩展程序升级到 2026-10 之前，请在每个调用位置处理拒绝错误。
变更前：
await shopify.cart.applyCartDiscount('FixedAmount', 'Winter discount', '5.00'); setDiscountApplied(true);变更后：
try { await shopify.cart.applyCartDiscount('FixedAmount', 'Winter discount', '5.00'); setDiscountApplied(true); } catch (error) { setDiscountApplied(false); showToast('Could not update the cart. Try again before payment.'); }如果您无法立即迁移，请将扩展程序保持在 2026-07 或更早版本。这些版本不受影响，您可以在处理好拒绝逻辑后再进行升级。
所需操作
为您扩展程序调用的每个购物车变更操作添加拒绝处理，然后设置 api_version = "2026-10"。未处理拒绝错误就进行升级的应用会发现其处理程序在未确认的写入操作处停止，这可能导致屏幕上保留旋转加载图标或跳过确认步骤。2026-07 在其 API 版本控制 的支持窗口结束前仍可正常工作。
相关文档
- Cart API
- 2026-10: 发布说明
- API版本控制