---
title: >-
  Making idempotency mandatory for inventory adjustments and refund mutations -
  Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/making-idempotency-mandatory-for-inventory-adjustments-and-refund-mutations
  md: >-
    https://shopify.dev/changelog/posts/making-idempotency-mandatory-for-inventory-adjustments-and-refund-mutations.md
metadata:
  effectiveApiVersion: 2026-04
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Breaking API Change
    handle: breaking-api-change
  indicatesActionRequired: true
  createdAt: '2025-12-05T14:05:59-05:00'
  postedAt: '2025-12-12T12:00:00-05:00'
  updatedAt: '2025-12-16T10:28:44-05:00'
  effectiveAt: '2025-12-12T12:00:00-05:00'
---

December 12, 2025

# Making idempotency mandatory for inventory adjustments and refund mutations

DateDecember 12, 2025

Version[2026-04](https://shopify.dev/changelog?api_version=2026-04)

Flags[Breaking API Change](https://shopify.dev/changelog?filter=breaking-api-change)[Action required](https://shopify.dev/changelog?action_required=true)

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)

This changelog relates to [concurrency protection features](https://shopify.dev/changelog/concurrency-protection-features).

We're making the [idempotent directive introduced here](https://shopify.dev/changelog/adding-idempotency-for-inventory-adjustments-and-refund-mutations) **mandatory** for the following mutations in version `2026-04`:

* [`refundCreate`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/refundCreate)
* [`inventoryShipmentReceive`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryShipmentReceive)
* [`inventoryAdjustQuantities`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryAdjustQuantities)
* [`inventoryMoveQuantities`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryMoveQuantities)
* [`inventorySetQuantities`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventorySetQuantities)
* [`inventorySetOnHandQuantities`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventorySetOnHandQuantities)
* [`inventoryShipmentCreateInTransit`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryShipmentCreateInTransit)
* [`inventoryShipmentCreate`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryShipmentCreate)
* [`inventoryTransferCreate`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryTransferCreate)
* [`inventoryTransferCreateAsReadyToShip`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryTransferCreateAsReadyToShip)
* [`inventoryTransferDuplicate`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryTransferDuplicate)
* [`inventoryTransferSetItems`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryTransferSetItems)
* [`inventorySetScheduledChanges`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventorySetScheduledChanges)
* [`inventoryActivate`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryActivate)
* [`inventoryShipmentAddItems`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/inventoryShipmentAddItems)
* [`locationActivate`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/locationActivate)
* [`locationDeactivate`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/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](https://shopify.dev/docs/api/usage/idempotent-requests).

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