`InventoryShipmentReceive` mutation now supports idempotency

Shopify Updates: 

InventoryShipmentReceive mutation now requires an idempotency key

The inventoryShipmentReceive mutation now requires an idempotencyKey field that prevents duplicate shipment receiving operations. You must provide an idempotency key with every request to ensure that repeated requests with the same key won't create duplicate inventory adjustments, helping you avoid accidental over-receiving of shipment items.

Key benefits:

  • Prevents duplicate inventory adjustments from network retries or multiple submissions.
  • Ensures consistent inventory levels even when mutation requests are repeated.
  • Maintains data integrity during shipment receiving workflows.

Breaking change:

The idempotencyKey field is now required for all inventoryShipmentReceive mutations.

Usage:

mutation inventoryShipmentReceive($input: InventoryShipmentReceiveInput!) {
  inventoryShipmentReceive(
    id: "gid://shopify/InventoryShipment/123"
    idempotencyKey: "0199150a-0776-7c59-b03a-c7bafe3f4dfc"
    lineItems: [
      {
        shipmentLineItemId: "gid://shopify/InventoryShipmentLineItem/789"
        quantity: 10
        reason: ACCEPTED
      }
    ]
  ) {
    inventoryShipment {
      id
    }
    userErrors {
      field
      message
    }
  }
}

The idempotency key must be unique per receiving operation and can be any string up to 255 characters. We recommend using UUID v7 for idempotency keys, as they provide guaranteed uniqueness and include timestamp information for better traceability.

Important:

Idempotency keys are cleared periodically to maintain system performance, so the same key can be reused after some time. However, you should always generate fresh keys for new operations to ensure proper idempotency protection.

Back to blog