Choose a version:

inventoryShipmentReceive

mutation

Requires write_inventory_shipments_received_items access scope. Also: The user must have permission to manage inventory.

Receive an inventory shipment.

Caution

As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive. As of 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 bulkReceiveActionbulkReceiveAction

•InventoryShipmentReceiveLineItemReason

The bulk receive action for the inventory shipment.

Anchor to dateReceiveddateReceived

•DateTime

The date the inventory shipment was initially received.

Anchor to idid

•ID!

required

The ID of the inventory shipment to receive.

Anchor to lineItemslineItems

•[InventoryShipmentReceiveItemInput!]

The list of receive line items for the inventory shipment.

Was this section helpful?

Anchor to InventoryShipmentReceivePayload returnsInventoryShipmentReceivePayload returns

Anchor to inventoryShipmentinventoryShipment •InventoryShipment: The inventory shipment with received items.
Anchor to userErrorsuserErrors •[InventoryShipmentReceiveUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Receives a shipment

Query

mutation inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {
  inventoryShipmentReceive(id: $id, lineItems: $lineItems) {
    userErrors {
      field
      message
    }
    inventoryShipment {
      id
      status
    }
  }
}

Variables

{
  "id": "gid://shopify/InventoryShipment/340744744",
  "lineItems": [
    {
      "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
      "quantity": 10,
      "reason": "ACCEPTED"
    }
  ]
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) { inventoryShipmentReceive(id: $id, lineItems: $lineItems) { userErrors { field message } inventoryShipment { id status } } }",
 "variables": {
    "id": "gid://shopify/InventoryShipment/340744744",
    "lineItems": [
      {
        "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
        "quantity": 10,
        "reason": "ACCEPTED"
      }
    ]
  }
}'

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 inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {
    inventoryShipmentReceive(id: $id, lineItems: $lineItems) {
      userErrors {
        field
        message
      }
      inventoryShipment {
        id
        status
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/InventoryShipment/340744744",
        "lineItems": [
            {
                "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
                "quantity": 10,
                "reason": "ACCEPTED"
            }
        ]
    },
  },
  );
  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 inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {
    inventoryShipmentReceive(id: $id, lineItems: $lineItems) {
      userErrors {
        field
        message
      }
      inventoryShipment {
        id
        status
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/InventoryShipment/340744744",
  "lineItems": [
    {
      "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
      "quantity": 10,
      "reason": "ACCEPTED"
    }
  ]
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {
      inventoryShipmentReceive(id: $id, lineItems: $lineItems) {
        userErrors {
          field
          message
        }
        inventoryShipment {
          id
          status
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/InventoryShipment/340744744",
        "lineItems": [
            {
                "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
                "quantity": 10,
                "reason": "ACCEPTED"
            }
        ]
    },
  },
});

Response

{
  "inventoryShipmentReceive": {
    "userErrors": [],
    "inventoryShipment": {
      "id": "gid://shopify/InventoryShipment/340744744",
      "status": "RECEIVED"
    }
  }
}

Receives a shipment with idempotency enabled (2026-01 onwards)

Query

mutation inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!], $idempotencyKey: String!) {
  inventoryShipmentReceive(id: $id, lineItems: $lineItems) @idempotent(key: $idempotencyKey) {
    userErrors {
      field
      message
    }
    inventoryShipment {
      id
      status
    }
  }
}

Variables

{
  "id": "gid://shopify/InventoryShipment/340744744",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "lineItems": [
    {
      "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
      "quantity": 10,
      "reason": "ACCEPTED"
    }
  ]
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!], $idempotencyKey: String!) { inventoryShipmentReceive(id: $id, lineItems: $lineItems) @idempotent(key: $idempotencyKey) { userErrors { field message } inventoryShipment { id status } } }",
 "variables": {
    "id": "gid://shopify/InventoryShipment/340744744",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "lineItems": [
      {
        "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
        "quantity": 10,
        "reason": "ACCEPTED"
      }
    ]
  }
}'

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 inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!], $idempotencyKey: String!) {
    inventoryShipmentReceive(id: $id, lineItems: $lineItems) @idempotent(key: $idempotencyKey) {
      userErrors {
        field
        message
      }
      inventoryShipment {
        id
        status
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/InventoryShipment/340744744",
        "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
        "lineItems": [
            {
                "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
                "quantity": 10,
                "reason": "ACCEPTED"
            }
        ]
    },
  },
  );
  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 inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!], $idempotencyKey: String!) {
    inventoryShipmentReceive(id: $id, lineItems: $lineItems) @idempotent(key: $idempotencyKey) {
      userErrors {
        field
        message
      }
      inventoryShipment {
        id
        status
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/InventoryShipment/340744744",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "lineItems": [
    {
      "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
      "quantity": 10,
      "reason": "ACCEPTED"
    }
  ]
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!], $idempotencyKey: String!) {
      inventoryShipmentReceive(id: $id, lineItems: $lineItems) @idempotent(key: $idempotencyKey) {
        userErrors {
          field
          message
        }
        inventoryShipment {
          id
          status
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/InventoryShipment/340744744",
        "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
        "lineItems": [
            {
                "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
                "quantity": 10,
                "reason": "ACCEPTED"
            }
        ]
    },
  },
});

Response

{
  "inventoryShipmentReceive": {
    "userErrors": [],
    "inventoryShipment": {
      "id": "gid://shopify/InventoryShipment/340744744",
      "status": "RECEIVED"
    }
  }
}

inventoryShipmentReceive 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 inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {

inventoryShipmentReceive(id: $id, lineItems: $lineItems) {

userErrors {

field

message

}

inventoryShipment {

status

}

}`,

{

variables: {

"id": "gid://shopify/InventoryShipment/340744744",

"lineItems": [

{

"shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",

"quantity": 10,

"reason": "ACCEPTED"

}

]

);

const json = await response.json();

return json.data;

}

GQL

mutation inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {
  inventoryShipmentReceive(id: $id, lineItems: $lineItems) {
    userErrors {
      field
      message
    }
    inventoryShipment {
      id
      status
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) { inventoryShipmentReceive(id: $id, lineItems: $lineItems) { userErrors { field message } inventoryShipment { id status } } }",
 "variables": {
    "id": "gid://shopify/InventoryShipment/340744744",
    "lineItems": [
      {
        "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
        "quantity": 10,
        "reason": "ACCEPTED"
      }
    ]
  }
}'

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 inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {
    inventoryShipmentReceive(id: $id, lineItems: $lineItems) {
      userErrors {
        field
        message
      }
      inventoryShipment {
        id
        status
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/InventoryShipment/340744744",
        "lineItems": [
            {
                "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
                "quantity": 10,
                "reason": "ACCEPTED"
            }
        ]
    },
  },
  );
  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 inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {
      inventoryShipmentReceive(id: $id, lineItems: $lineItems) {
        userErrors {
          field
          message
        }
        inventoryShipment {
          id
          status
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/InventoryShipment/340744744",
        "lineItems": [
            {
                "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
                "quantity": 10,
                "reason": "ACCEPTED"
            }
        ]
    },
  },
});

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 inventoryShipmentReceive($id: ID!, $lineItems: [InventoryShipmentReceiveItemInput!]) {
    inventoryShipmentReceive(id: $id, lineItems: $lineItems) {
      userErrors {
        field
        message
      }
      inventoryShipment {
        id
        status
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/InventoryShipment/340744744",
  "lineItems": [
    {
      "shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",
      "quantity": 10,
      "reason": "ACCEPTED"
    }
  ]
}

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

Input variables

JSON

{

"id": "gid://shopify/InventoryShipment/340744744",

"lineItems": [

{

"shipmentLineItemId": "gid://shopify/InventoryShipmentLineItem/925690278",

"quantity": 10,

"reason": "ACCEPTED"

}

]

}

Response

JSON

{

"inventoryShipmentReceive": {

"userErrors": [],

"inventoryShipment": {

"id": "gid://shopify/InventoryShipment/340744744",

"status": "RECEIVED"

}