Idempotency directive not required or preventing duplicate inventoryAdjustQuantities requests

GraphQL Admin API Troubleshooting
1

Hi,

I have tried the following inventoryAdjustQuantities mutations via the 2026-04 Admin GraphQL endpoint, one with and one without an idempotency directive. I ran both queries 3 times.

My expectation was the following:

  • The query with the idempotency directive would result in one successful adjustment and 2 failed adjustments. This is based on the assumption that, because I did not update the idempotency key value, the second and third request would be rejected as duplicates
  • The query without the directive would result in no successful adjustments since it does not contain the required idempotency directive.

The actual results were 3 successful adjustments for both queries.

Query 1 with idempotency

mutation InventoryAdjustWithIdempotency($input: InventoryAdjustQuantitiesInput!) {
  inventoryAdjustQuantities(input: $input)  
  @idempotent(key: "3f5b6ebf-143c-4da5-8d0f-fb8553bfd85d") {
    inventoryAdjustmentGroup {
      id
      reason
      referenceDocumentUri
      changes(quantityNames: ["available"]) {
        name
        delta
        quantityAfterChange
      }
    }
    userErrors {
      field
      message
    }
  }
}

Query 2, no idempotency directive

mutation InventoryAdjustWithoutIdempotency($input: InventoryAdjustQuantitiesInput!) {
  inventoryAdjustQuantities(input: $input) {
    inventoryAdjustmentGroup {
      id
      reason
      referenceDocumentUri
      changes(quantityNames: ["available"]) {
        name
        delta
        quantityAfterChange
      }
    }
    userErrors {
      field
      message
    }
  }
}

I supplied valid variables each time:

{
  "input": {
    "name": "available",
    "reason": "correction",
    "changes": [
      {
        "delta": 4,
        "changeFromQuantity": null,
        "inventoryItemId": "gid://shopify/InventoryItem/xxx",
        "locationId": "gid://shopify/Location/xxx"
      }
    ]
  }
}

What am I missing? This does not seem to make sense given the docs. I also tried this on the 2026-01 endpoint with the same results, although I expected the same results for the second query since 2026-01 does not require the directive.

I posted this same issue as a response to the appropriate changelog post: Making idempotency mandatory for inventory adjustments and refund mutations

Posting here too because I don’t know if those posts are monitored for responses

Making idempotency mandatory for inventory adjustments and refund mutations
Idempotency key for store credit update APIs
2

Hi @lrotherfield,

I’ve been able to replicate this behaviour on my own test store as well, with the idempotency requirements not applying, and being able to make multiple adjustments with the same key.

I’ve looked into this further and discussed this with our developers internally, and we can confirm that this is actually expected behaviour for certain stores at this time.

We are currently rolling out this update in batches, with expected full release to all stores by the end of the week. So if your store was not included one of the batches that has already been updated, then the behaviour you experienced with version 2026-04 is still expected.

Our developers do apologize for the inconvenience of this, and if you would like we can manually enable the update on any stores you’re working with before the full roll out, however we will need you to reach out via the Shopify Help Center while logged into the store’s owner account to make this request (or get the store owner to reach out directly) as we do need to be fully authenticated with the Store Owner in order to apply this update manually.

Otherwise, you can also wait for the full roll out to all stores automatically by the end of the week.

1 Like
4

Hey @Kellan-Shopify ,

Thanks for the quick response. Regarding 2026-01 I am expecting the second and third requests with the same idempotency key to fail the same way I’m expecting them to fail in 2026-04. Is this valid or am I misunderstanding how idempotency works? Particularly, I am assuming the key protects 2 identical requests from running even if they are run a few minutes apart, not concurrently.

The scenario for this would be receiving a 500 error from Shopify’s API but the request actually being processed. Currently I have to manually check if the request processed before running the request again, however if the idempotency keys work how I am assuming, I could just retry the request safely

Cheers

Luke

5

Hi Luke (@lrotherfield),

I can confirm that you are correct in your assumptions here in that the inventoryAdjustQuantities mutation will fail on API version 2026-01 (and above) when using the same idempotency key that’s already been used.

The requests will fail with all duplicate requests made up to 24 hours after the initial request, so you will be able to retry the request safely as many times as you like without it processing additional adjustments, as long as the idempotency key is identical.

This will be rolled out with the update I mentioned above, so will be enabled on all stores by the end of the week and we can enable it manually on specific stores before then as mentioned previously.

Additionally if you wanted to confirm that the adjustment was made without querying the API directly, you can also subscribe to the inventory_levels/update webhook to receive notifications of all inventory level updates, including adjustments made via the API.

6

I can confirm that idempotency works on 2026-01 and 2026-04 as expected after requesting it is activated on my store. Assume this will be the case for all stores in a week as per Kellan’s first response

1 Like