Choose a version:

inventoryMoveQuantities

mutation

Requires write_inventory access scope. Also: The user must have a permission to move an inventory.

Moves inventory quantities for a single inventory item between different states at a single location. Use this mutation to reallocate inventory across quantity states without moving it between locations.

Each change specifies the quantity to move, the source state and location, and the destination state and location. The mutation returns an InventoryAdjustmentGroup that tracks all changes made in a single operation, providing an audit trail with the reason and reference document URI.

Caution

As of version 2026-01, this mutation supports an optional idempotency key using the @idempotent directive. As of version 2026-04, the idempotency key is required and must be provided using the @idempotent directive. For more information, see the idempotency documentation.

Anchor to Arguments

Arguments

Anchor to inputinput

•InventoryMoveQuantitiesInput!

required

The information required to move inventory quantities.

Was this section helpful?

Anchor to InventoryMoveQuantitiesPayload returnsInventoryMoveQuantitiesPayload returns

Anchor to inventoryAdjustmentGroupinventoryAdjustmentGroup •InventoryAdjustmentGroup: The group of changes made by the operation.
Anchor to userErrorsuserErrors •[InventoryMoveQuantitiesUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Move 10 items from available to reserved, with reason damaged.

Query

mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {
  inventoryMoveQuantities(input: $input) {
    userErrors {
      field
      message
      code
    }
    inventoryAdjustmentGroup {
      createdAt
      reason
      referenceDocumentUri
      changes(quantityNames: $quantityNames) {
        name
        delta
      }
    }
  }
}

Variables

{
  "input": {
    "reason": "damaged",
    "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
    "changes": [
      {
        "quantity": 10,
        "inventoryItemId": "gid://shopify/InventoryItem/30322695",
        "from": {
          "locationId": "gid://shopify/Location/124656943",
          "name": "available",
          "ledgerDocumentUri": null
        },
        "to": {
          "locationId": "gid://shopify/Location/124656943",
          "name": "reserved",
          "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
        }
      }
    ]
  },
  "quantityNames": [
    "committed",
    "reserved",
    "safety_stock",
    "quality_control",
    "damaged",
    "available",
    "on_hand",
    "incoming"
  ]
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) { inventoryMoveQuantities(input: $input) { userErrors { field message code } inventoryAdjustmentGroup { createdAt reason referenceDocumentUri changes(quantityNames: $quantityNames) { name delta } } } }",
 "variables": {
    "input": {
      "reason": "damaged",
      "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
      "changes": [
        {
          "quantity": 10,
          "inventoryItemId": "gid://shopify/InventoryItem/30322695",
          "from": {
            "locationId": "gid://shopify/Location/124656943",
            "name": "available",
            "ledgerDocumentUri": null
          },
          "to": {
            "locationId": "gid://shopify/Location/124656943",
            "name": "reserved",
            "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
          }
        }
      ]
    },
    "quantityNames": [
      "committed",
      "reserved",
      "safety_stock",
      "quality_control",
      "damaged",
      "available",
      "on_hand",
      "incoming"
    ]
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {
    inventoryMoveQuantities(input: $input) {
      userErrors {
        field
        message
        code
      }
      inventoryAdjustmentGroup {
        createdAt
        reason
        referenceDocumentUri
        changes(quantityNames: $quantityNames) {
          name
          delta
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "reason": "damaged",
            "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
            "changes": [
                {
                    "quantity": 10,
                    "inventoryItemId": "gid://shopify/InventoryItem/30322695",
                    "from": {
                        "locationId": "gid://shopify/Location/124656943",
                        "name": "available",
                        "ledgerDocumentUri": null
                    },
                    "to": {
                        "locationId": "gid://shopify/Location/124656943",
                        "name": "reserved",
                        "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
                    }
                }
            ]
        },
        "quantityNames": [
            "committed",
            "reserved",
            "safety_stock",
            "quality_control",
            "damaged",
            "available",
            "on_hand",
            "incoming"
        ]
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {
    inventoryMoveQuantities(input: $input) {
      userErrors {
        field
        message
        code
      }
      inventoryAdjustmentGroup {
        createdAt
        reason
        referenceDocumentUri
        changes(quantityNames: $quantityNames) {
          name
          delta
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "reason": "damaged",
    "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
    "changes": [
      {
        "quantity": 10,
        "inventoryItemId": "gid://shopify/InventoryItem/30322695",
        "from": {
          "locationId": "gid://shopify/Location/124656943",
          "name": "available",
          "ledgerDocumentUri": null
        },
        "to": {
          "locationId": "gid://shopify/Location/124656943",
          "name": "reserved",
          "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
        }
      }
    ]
  },
  "quantityNames": [
    "committed",
    "reserved",
    "safety_stock",
    "quality_control",
    "damaged",
    "available",
    "on_hand",
    "incoming"
  ]
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {
      inventoryMoveQuantities(input: $input) {
        userErrors {
          field
          message
          code
        }
        inventoryAdjustmentGroup {
          createdAt
          reason
          referenceDocumentUri
          changes(quantityNames: $quantityNames) {
            name
            delta
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "reason": "damaged",
            "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
            "changes": [
                {
                    "quantity": 10,
                    "inventoryItemId": "gid://shopify/InventoryItem/30322695",
                    "from": {
                        "locationId": "gid://shopify/Location/124656943",
                        "name": "available",
                        "ledgerDocumentUri": null
                    },
                    "to": {
                        "locationId": "gid://shopify/Location/124656943",
                        "name": "reserved",
                        "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
                    }
                }
            ]
        },
        "quantityNames": [
            "committed",
            "reserved",
            "safety_stock",
            "quality_control",
            "damaged",
            "available",
            "on_hand",
            "incoming"
        ]
    },
  },
});

Response

{
  "inventoryMoveQuantities": {
    "userErrors": [],
    "inventoryAdjustmentGroup": {
      "createdAt": "2024-09-12T01:06:28Z",
      "reason": "Damaged",
      "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
      "changes": [
        {
          "name": "available",
          "delta": -10
        },
        {
          "name": "reserved",
          "delta": 10
        }
      ]
    }
  }
}

inventoryMoveQuantities reference

Examples

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {

inventoryMoveQuantities(input: $input) {

userErrors {

field

message

code

}

inventoryAdjustmentGroup {

createdAt

reason

referenceDocumentUri

changes(quantityNames: $quantityNames) {

name

delta

}

}`,

{

variables: {

"input": {

"reason": "damaged",

"referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",

"changes": [

{

"quantity": 10,

"inventoryItemId": "gid://shopify/InventoryItem/30322695",

"from": {

"locationId": "gid://shopify/Location/124656943",

"name": "available",

"ledgerDocumentUri": null

"to": {

"locationId": "gid://shopify/Location/124656943",

"name": "reserved",

"ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"

}

]

"quantityNames": [

"committed",

"reserved",

"safety_stock",

"quality_control",

"damaged",

"available",

"on_hand",

"incoming"

]

);

const json = await response.json();

return json.data;

}

GQL

mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {
  inventoryMoveQuantities(input: $input) {
    userErrors {
      field
      message
      code
    }
    inventoryAdjustmentGroup {
      createdAt
      reason
      referenceDocumentUri
      changes(quantityNames: $quantityNames) {
        name
        delta
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) { inventoryMoveQuantities(input: $input) { userErrors { field message code } inventoryAdjustmentGroup { createdAt reason referenceDocumentUri changes(quantityNames: $quantityNames) { name delta } } } }",
 "variables": {
    "input": {
      "reason": "damaged",
      "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
      "changes": [
        {
          "quantity": 10,
          "inventoryItemId": "gid://shopify/InventoryItem/30322695",
          "from": {
            "locationId": "gid://shopify/Location/124656943",
            "name": "available",
            "ledgerDocumentUri": null
          },
          "to": {
            "locationId": "gid://shopify/Location/124656943",
            "name": "reserved",
            "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
          }
        }
      ]
    },
    "quantityNames": [
      "committed",
      "reserved",
      "safety_stock",
      "quality_control",
      "damaged",
      "available",
      "on_hand",
      "incoming"
    ]
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {
    inventoryMoveQuantities(input: $input) {
      userErrors {
        field
        message
        code
      }
      inventoryAdjustmentGroup {
        createdAt
        reason
        referenceDocumentUri
        changes(quantityNames: $quantityNames) {
          name
          delta
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "reason": "damaged",
            "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
            "changes": [
                {
                    "quantity": 10,
                    "inventoryItemId": "gid://shopify/InventoryItem/30322695",
                    "from": {
                        "locationId": "gid://shopify/Location/124656943",
                        "name": "available",
                        "ledgerDocumentUri": null
                    },
                    "to": {
                        "locationId": "gid://shopify/Location/124656943",
                        "name": "reserved",
                        "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
                    }
                }
            ]
        },
        "quantityNames": [
            "committed",
            "reserved",
            "safety_stock",
            "quality_control",
            "damaged",
            "available",
            "on_hand",
            "incoming"
        ]
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {
      inventoryMoveQuantities(input: $input) {
        userErrors {
          field
          message
          code
        }
        inventoryAdjustmentGroup {
          createdAt
          reason
          referenceDocumentUri
          changes(quantityNames: $quantityNames) {
            name
            delta
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "reason": "damaged",
            "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
            "changes": [
                {
                    "quantity": 10,
                    "inventoryItemId": "gid://shopify/InventoryItem/30322695",
                    "from": {
                        "locationId": "gid://shopify/Location/124656943",
                        "name": "available",
                        "ledgerDocumentUri": null
                    },
                    "to": {
                        "locationId": "gid://shopify/Location/124656943",
                        "name": "reserved",
                        "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
                    }
                }
            ]
        },
        "quantityNames": [
            "committed",
            "reserved",
            "safety_stock",
            "quality_control",
            "damaged",
            "available",
            "on_hand",
            "incoming"
        ]
    },
  },
});

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation inventoryMoveQuantities($input: InventoryMoveQuantitiesInput!, $quantityNames: [String!]) {
    inventoryMoveQuantities(input: $input) {
      userErrors {
        field
        message
        code
      }
      inventoryAdjustmentGroup {
        createdAt
        reason
        referenceDocumentUri
        changes(quantityNames: $quantityNames) {
          name
          delta
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "reason": "damaged",
    "referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",
    "changes": [
      {
        "quantity": 10,
        "inventoryItemId": "gid://shopify/InventoryItem/30322695",
        "from": {
          "locationId": "gid://shopify/Location/124656943",
          "name": "available",
          "ledgerDocumentUri": null
        },
        "to": {
          "locationId": "gid://shopify/Location/124656943",
          "name": "reserved",
          "ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"
        }
      }
    ]
  },
  "quantityNames": [
    "committed",
    "reserved",
    "safety_stock",
    "quality_control",
    "damaged",
    "available",
    "on_hand",
    "incoming"
  ]
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"input": {

"reason": "damaged",

"referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",

"changes": [

{

"quantity": 10,

"inventoryItemId": "gid://shopify/InventoryItem/30322695",

"from": {

"locationId": "gid://shopify/Location/124656943",

"name": "available",

"ledgerDocumentUri": null

"to": {

"locationId": "gid://shopify/Location/124656943",

"name": "reserved",

"ledgerDocumentUri": "logistics://toronto.warehouse/work-orders/2023-01-04/2"

}

]

"quantityNames": [

"committed",

"reserved",

"safety_stock",

"quality_control",

"damaged",

"available",

"on_hand",

"incoming"

]

}

Response

JSON

{

"inventoryMoveQuantities": {

"userErrors": [],

"inventoryAdjustmentGroup": {

"createdAt": "2024-09-12T01:06:28Z",

"reason": "Damaged",

"referenceDocumentUri": "logistics://some.warehouse/take/2023-01-23T13:14:15Z",

"changes": [

{

"name": "available",

"delta": -10

{

"name": "reserved",

"delta": 10

}

]

}