此更新日志涉及 并发保护功能。
我们正将此处引入的幂等指令变为 幂等指令 强制性的 ，适用于以下在版本 2026-04中的变更操作：
- refundCreate
- inventoryShipmentReceive
- inventoryAdjustQuantities
- inventoryMoveQuantities
- inventorySetQuantities
- inventorySetOnHandQuantities
- inventoryShipmentCreateInTransit
- inventoryShipmentCreate
- inventoryTransferCreate
- inventoryTransferCreateAsReadyToShip
- inventoryTransferDuplicate
- inventoryTransferSetItems
- inventorySetScheduledChanges
- inventoryActivate
- inventoryShipmentAddItems
- locationActivate
- locationDeactivate
注意：即使幂等指令在模式层面未显示为强制性，如果在调用这些变更操作时未提供幂等指令，将在运行时导致错误。
您需要做什么
使用这些变更操作的开发者必须更新其应用程序逻辑，以包含 @idempotent 指令，然后再迁移到版本 2026-04
如何使用该指令
幂等键是一个唯一标识符（建议使用 UUID），您在发起变更操作请求时需提供该标识符（通常，您应在页面加载后以及成功操作后重新生成此密钥）。如果因网络问题或超时而重试具有相同幂等键的同一请求，Shopify 会将其识别为重复请求，并确保库存仅调整一次（或退款仅创建一次），从而防止重复计数。它将返回原始操作的结果，而不是创建一个新操作。
示例用法：
mutation { inventoryAdjustQuantities( input: { reason: "restock" name: "available" changes: [{ delta: 5 inventoryItemId: "gid://shopify/InventoryItem/123" locationId: "gid://shopify/Location/456" }] } ) @idempotent(key: "4f5b6ebf-143c-4da5-8d0f-fb8553bfd85d") { inventoryAdjustmentGroup { id } userErrors { code message } } }我们做出此变更的原因
幂等键对于构建健壮、可用于生产环境的集成至关重要。重复的库存调整和重复退款长期以来一直是商家和 Shopify 的痛点，导致库存不一致和财务损失。将幂等性作为退款和库存变更加密的强制要求，将有助于缓解这些问题。
如需了解如何实现幂等性的更多信息，请参阅 我们的文档。
错误代码
如果您的幂等键使用出现问题，您将收到以下错误代码之一：
- IDEMPOTENCY_CONCURRENT_REQUESTIDEMPOTENCY_CONCURRENT_REQUEST：当前正在处理具有相同幂等键的另一个请求
- IDEMPOTENCY_KEY_PARAMETER_MISMATCHIDEMPOTENCY_KEY_PARAMETER_MISMATCH：相同的幂等键使用了不同的参数