Concurrency protection features for inventory and refund mutations

This changelog consolidates all updates related to concurrency protection features for inventory and refund mutations.

Compare and swap changes

To prevent race conditions in inventory updates, we're introducing compare and swap protection through the changeFromQuantity field across multiple API versions:

• 2026-01 : Introducing a changeFromQuantity field for various inventory mutations
• 2026-01: Introducing a changeFromQuantity field for the inventorySetQuantities mutation and deprecating the old compare And swap fields
• 2026-04: Making the changeFromQuantity field required (with explict opt-out) for various inventory mutations (BREAKING)
• 2026-04: Making the changeFromQuantity field required (with explict opt-out) for the inventorySetQuantities mutation and removing the old compare And swap fields (BREAKING)

Idempotency changes

To prevent duplicate operations when requests are retried, we're introducing idempotency protection through the idempotent directive:

• 2026-01: Introducing an optional idempotent directive for various inventory and refund mutations
• 2026-04 Making the idempotent directive required for various inventory and refund mutations (BREAKING)

Why we made these changes

Most inventory adjustments lack concurrency and idempotency protection, leaving systems vulnerable to race conditions, duplicate updates, and integrity issues—especially when commands are retried due to network disruptions. To solve this we will standardize concurrency and idempotency checks across Inventory APIs.

For more information, refer to our idempotency and compare and swap docs.