Making idempotency mandatory for inventory adjustments and refund mutations

This changelog relates to concurrency protection features.

We're making the idempotent directive introduced here mandatory for the following mutations in version 2026-04:

• refundCreate
• inventoryShipmentReceive
• inventoryAdjustQuantities
• inventoryMoveQuantities
• inventorySetQuantities
• inventorySetOnHandQuantities
• inventoryShipmentCreateInTransit
• inventoryShipmentCreate
• inventoryTransferCreate
• inventoryTransferCreateAsReadyToShip
• inventoryTransferDuplicate
• inventoryTransferSetItems
• inventorySetScheduledChanges
• inventoryActivate
• inventoryShipmentAddItems
• locationActivate
• locationDeactivate

Note: Even though the idempotency directive doesn't show up as mandatory at the schema level, calling these mutations without an idempotency directive will result in an error at runtime.

What you need to do

Developers using these mutations must update their application logic to include the @idempotent directive before migrating to version 2026-04

How to use the directive

An idempotency key is a unique identifier (we recommend using a UUID) that you provide when making a mutation request (generally, you would regenerate this key on page load and after successful operations). If you retry the same request with the same idempotency key due to network issues or timeouts, Shopify will recognize it as a duplicate and ensure the inventory is only adjusted once (or that the refund is only created once), protecting against double-counting. It will return the result of the original operation instead of creating a new one.

Example usage:

  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
      }
    }
  }

Why we made this change

Idempotency keys are essential for building robust, production-ready integrations. Duplicate inventory adjustments and duplicate refunds have long been a pain-point for merchants and for Shopify, resulting in inventory inconsistencies and financial losses. Making idempotency mandatory for our refund and inventory mutations will mitigate these problems.

For more information on how to implement idempotency, refer to our docs.

Error codes

If there's an issue with your idempotency key usage, you'll receive one of these error codes:

• IDEMPOTENCY_CONCURRENT_REQUEST: Another request with the same idempotency key is currently being processed
• IDEMPOTENCY_KEY_PARAMETER_MISMATCH: The same idempotency key was used with different parameters