Adding idempotency for inventory adjustments and refund mutations

This changelog relates to concurrency protection features.

We're introducing idempotency keys for several inventory and refund mutations. This enhancement helps you build more reliable integrations by preventing duplicate operations when retrying failed requests. You pass idempotency keys in using an idempotent directive. Refer to the idempotent requests docs for more details.

The following mutations now support the optional idempotent directive:

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

Note: While the idempotent directive is optional for now, we plan to make it mandatory for these mutations in 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. Network failures and timeouts are inevitable, and without idempotency protection, retrying requests could lead to duplicate refunds, incorrect inventory counts, or other data inconsistencies. Making this feature publicly available gives you the tools to handle these scenarios safely.

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.