Choose a version:

inventoryPurchaseOrder

query

Requires read_inventory_purchase_orders access scope. Also: The user must have permission to view purchase orders. The shop must have access to the physical inventory feature preview.

Returns an InventoryPurchaseOrder object by ID.

Note

This query is available only in the unstable API version and to development stores that have enabled the Physical inventory feature preview.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the inventory purchase order.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to InventoryPurchaseOrderInventoryPurchaseOrder

•InventoryPurchaseOrder

A purchase order represents an agreement from a merchant to buy goods or services from a supplier. While the agreement is captured on the merchant's side as a purchase order, it’s recorded as a sales order on the supplier side.

Note

This object is available only in the unstable API version and to development stores that have enabled the Physical inventory feature preview.

Anchor to archivedAtarchivedAt

•DateTime

The date and time the purchase order was archived.

Anchor to currencycurrency

•CurrencyCode!

non-null

The currency for the purchase order's cost values. The shop's currency will be used if one isn't provided during creation.

Anchor to dateCreateddateCreated

•DateTime!

non-null

The date and time the purchase order was placed.

Anchor to destinationdestination

•LocationSnapshot

The target containing the destination location of the purchase order.

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to lineItemslineItems

•InventoryPurchaseOrderLineItemConnection!

non-null

A list of the purchase order's line items.

Arguments

Anchor to afterafter

•String

The elements that come after the specified cursor.

Anchor to beforebefore

•String

The elements that come before the specified cursor.

Anchor to firstfirst

•Int

The first n elements from the paginated list.

Anchor to lastlast

•Int

The last n elements from the paginated list.

Anchor to lineItemIdlineItemId

•ID

ID of the purchase order line item.

Anchor to queryquery

•String

A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.

Anchor to default •string: Filter by a case-insensitive search of multiple fields in a document.
Anchor to id •id: Filter by id range.
Anchor to incoming_quantity •integer
Anchor to supplier_sku •string
Anchor to title •string
Anchor to unit_cost •float
Anchor to variant_id •id

Anchor to reversereverse

•Boolean

Default:false

Reverse the order of the underlying list.

Anchor to sortKeysortKey

•PurchaseOrderLineItemSortKeys

Default:ID

Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.

Anchor to namename

•String!

non-null

The name of the purchase order.

Anchor to orderedAtorderedAt

•DateTime

The date and time the purchase order was confirmed with the supplier.

Anchor to originorigin

•InventorySupplierSnapshot

The supplier snapshot where the purchase order originates from.

Anchor to referenceNamereferenceName

•String

An external reference name for the purchase order.

Anchor to statusstatus

•InventoryPurchaseOrderStatus!

non-null

The current status of the inventory purchase order.

Was this section helpful?

Examples

Retrieve a purchase order with its supplier, destination, and line items

Description

Retrieve an inventory purchase order by ID. `destination` is a point-in-time snapshot of the location (its `name`, `address`, and `snapshottedAt` reflect the values when the order was created), with `destination.location` linking to the current live Location. `origin.supplier` returns the supplier's current live details. Also returns the order's status, currency, dates, and the ordered line items with their quantities and costs. This query is part of the [physical inventory feature preview](https://shopify.dev/changelog/physical-inventory-feature-preview).

Query

query InventoryPurchaseOrder($id: ID!) {
  inventoryPurchaseOrder(id: $id) {
    id
    name
    status
    referenceName
    currency
    dateCreated
    orderedAt
    origin {
      supplier {
        name
      }
    }
    destination {
      name
      snapshottedAt
      location {
        id
        name
      }
    }
    lineItems(first: 10) {
      nodes {
        id
        title
        variantTitle
        supplierSku
        totalQuantity
        unitCost {
          amount
          currencyCode
        }
        totalCost {
          amount
          currencyCode
        }
      }
    }
  }
}

Variables

{
  "id": "gid://shopify/InventoryPurchaseOrder/884380239"
}

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": "query InventoryPurchaseOrder($id: ID!) { inventoryPurchaseOrder(id: $id) { id name status referenceName currency dateCreated orderedAt origin { supplier { name } } destination { name snapshottedAt location { id name } } lineItems(first: 10) { nodes { id title variantTitle supplierSku totalQuantity unitCost { amount currencyCode } totalCost { amount currencyCode } } } } }",
 "variables": {
    "id": "gid://shopify/InventoryPurchaseOrder/884380239"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query InventoryPurchaseOrder($id: ID!) {
    inventoryPurchaseOrder(id: $id) {
      id
      name
      status
      referenceName
      currency
      dateCreated
      orderedAt
      origin {
        supplier {
          name
        }
      }
      destination {
        name
        snapshottedAt
        location {
          id
          name
        }
      }
      lineItems(first: 10) {
        nodes {
          id
          title
          variantTitle
          supplierSku
          totalQuantity
          unitCost {
            amount
            currencyCode
          }
          totalCost {
            amount
            currencyCode
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/InventoryPurchaseOrder/884380239"
    },
  },
  );
  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
  query InventoryPurchaseOrder($id: ID!) {
    inventoryPurchaseOrder(id: $id) {
      id
      name
      status
      referenceName
      currency
      dateCreated
      orderedAt
      origin {
        supplier {
          name
        }
      }
      destination {
        name
        snapshottedAt
        location {
          id
          name
        }
      }
      lineItems(first: 10) {
        nodes {
          id
          title
          variantTitle
          supplierSku
          totalQuantity
          unitCost {
            amount
            currencyCode
          }
          totalCost {
            amount
            currencyCode
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/InventoryPurchaseOrder/884380239"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query InventoryPurchaseOrder($id: ID!) {
      inventoryPurchaseOrder(id: $id) {
        id
        name
        status
        referenceName
        currency
        dateCreated
        orderedAt
        origin {
          supplier {
            name
          }
        }
        destination {
          name
          snapshottedAt
          location {
            id
            name
          }
        }
        lineItems(first: 10) {
          nodes {
            id
            title
            variantTitle
            supplierSku
            totalQuantity
            unitCost {
              amount
              currencyCode
            }
            totalCost {
              amount
              currencyCode
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/InventoryPurchaseOrder/884380239"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query InventoryPurchaseOrder($id: ID!) {
  inventoryPurchaseOrder(id: $id) {
    id
    name
    status
    referenceName
    currency
    dateCreated
    orderedAt
    origin {
      supplier {
        name
      }
    }
    destination {
      name
      snapshottedAt
      location {
        id
        name
      }
    }
    lineItems(first: 10) {
      nodes {
        id
        title
        variantTitle
        supplierSku
        totalQuantity
        unitCost {
          amount
          currencyCode
        }
        totalCost {
          amount
          currencyCode
        }
      }
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/InventoryPurchaseOrder/884380239"
}'

Direct API Access

const response = await fetch('shopify:admin/api/unstable/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query InventoryPurchaseOrder($id: ID!) {
        inventoryPurchaseOrder(id: $id) {
          id
          name
          status
          referenceName
          currency
          dateCreated
          orderedAt
          origin {
            supplier {
              name
            }
          }
          destination {
            name
            snapshottedAt
            location {
              id
              name
            }
          }
          lineItems(first: 10) {
            nodes {
              id
              title
              variantTitle
              supplierSku
              totalQuantity
              unitCost {
                amount
                currencyCode
              }
              totalCost {
                amount
                currencyCode
              }
            }
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/InventoryPurchaseOrder/884380239"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "inventoryPurchaseOrder": {
    "id": "gid://shopify/InventoryPurchaseOrder/884380239",
    "name": "PO-1001",
    "status": "ORDERED",
    "referenceName": "SNOWDEVIL-ERP-420",
    "currency": "CAD",
    "dateCreated": "2019-08-19T00:00:00Z",
    "orderedAt": "2019-08-20T00:00:00Z",
    "origin": {
      "supplier": {
        "name": "Vans"
      }
    },
    "destination": {
      "name": "Ottawa Store",
      "snapshottedAt": "2019-08-19T00:00:00Z",
      "location": {
        "id": "gid://shopify/Location/346779380",
        "name": "Ottawa Store"
      }
    },
    "lineItems": {
      "nodes": [
        {
          "id": "gid://shopify/InventoryPurchaseOrderLineItem/387823291",
          "title": "Element",
          "variantTitle": "151cm",
          "supplierSku": "snowboard-inc-element-151",
          "totalQuantity": 10,
          "unitCost": {
            "amount": "10.0",
            "currencyCode": "CAD"
          },
          "totalCost": {
            "amount": "107.0",
            "currencyCode": "CAD"
          }
        },
        {
          "id": "gid://shopify/InventoryPurchaseOrderLineItem/593108211",
          "title": "Element",
          "variantTitle": "151cm",
          "supplierSku": "snowboard-inc-element-151",
          "totalQuantity": 10,
          "unitCost": {
            "amount": "10.0",
            "currencyCode": "CAD"
          },
          "totalCost": {
            "amount": "107.0",
            "currencyCode": "CAD"
          }
        }
      ]
    }
  }
}

Retrieve a purchase order with its supplier, destination, and line items

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

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

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

const response = await admin.graphql(

`#graphql

query InventoryPurchaseOrder($id: ID!) {

inventoryPurchaseOrder(id: $id) {

name

status

referenceName

currency

dateCreated

orderedAt

origin {

supplier {

name

}

destination {

name

snapshottedAt

location {

name

}

lineItems(first: 10) {

nodes {

title

variantTitle

supplierSku

totalQuantity

unitCost {

amount

currencyCode

}

totalCost {

amount

currencyCode

}

}`,

{

variables: {

"id": "gid://shopify/InventoryPurchaseOrder/884380239"

);

const json = await response.json();

return json.data;

}

GQL

query InventoryPurchaseOrder($id: ID!) {
  inventoryPurchaseOrder(id: $id) {
    id
    name
    status
    referenceName
    currency
    dateCreated
    orderedAt
    origin {
      supplier {
        name
      }
    }
    destination {
      name
      snapshottedAt
      location {
        id
        name
      }
    }
    lineItems(first: 10) {
      nodes {
        id
        title
        variantTitle
        supplierSku
        totalQuantity
        unitCost {
          amount
          currencyCode
        }
        totalCost {
          amount
          currencyCode
        }
      }
    }
  }
}

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": "query InventoryPurchaseOrder($id: ID!) { inventoryPurchaseOrder(id: $id) { id name status referenceName currency dateCreated orderedAt origin { supplier { name } } destination { name snapshottedAt location { id name } } lineItems(first: 10) { nodes { id title variantTitle supplierSku totalQuantity unitCost { amount currencyCode } totalCost { amount currencyCode } } } } }",
 "variables": {
    "id": "gid://shopify/InventoryPurchaseOrder/884380239"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query InventoryPurchaseOrder($id: ID!) {
    inventoryPurchaseOrder(id: $id) {
      id
      name
      status
      referenceName
      currency
      dateCreated
      orderedAt
      origin {
        supplier {
          name
        }
      }
      destination {
        name
        snapshottedAt
        location {
          id
          name
        }
      }
      lineItems(first: 10) {
        nodes {
          id
          title
          variantTitle
          supplierSku
          totalQuantity
          unitCost {
            amount
            currencyCode
          }
          totalCost {
            amount
            currencyCode
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/InventoryPurchaseOrder/884380239"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query InventoryPurchaseOrder($id: ID!) {
      inventoryPurchaseOrder(id: $id) {
        id
        name
        status
        referenceName
        currency
        dateCreated
        orderedAt
        origin {
          supplier {
            name
          }
        }
        destination {
          name
          snapshottedAt
          location {
            id
            name
          }
        }
        lineItems(first: 10) {
          nodes {
            id
            title
            variantTitle
            supplierSku
            totalQuantity
            unitCost {
              amount
              currencyCode
            }
            totalCost {
              amount
              currencyCode
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/InventoryPurchaseOrder/884380239"
    },
  },
});

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
  query InventoryPurchaseOrder($id: ID!) {
    inventoryPurchaseOrder(id: $id) {
      id
      name
      status
      referenceName
      currency
      dateCreated
      orderedAt
      origin {
        supplier {
          name
        }
      }
      destination {
        name
        snapshottedAt
        location {
          id
          name
        }
      }
      lineItems(first: 10) {
        nodes {
          id
          title
          variantTitle
          supplierSku
          totalQuantity
          unitCost {
            amount
            currencyCode
          }
          totalCost {
            amount
            currencyCode
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/InventoryPurchaseOrder/884380239"
}

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

Shopify CLI

shopify app execute \
--query \
'query InventoryPurchaseOrder($id: ID!) {
  inventoryPurchaseOrder(id: $id) {
    id
    name
    status
    referenceName
    currency
    dateCreated
    orderedAt
    origin {
      supplier {
        name
      }
    }
    destination {
      name
      snapshottedAt
      location {
        id
        name
      }
    }
    lineItems(first: 10) {
      nodes {
        id
        title
        variantTitle
        supplierSku
        totalQuantity
        unitCost {
          amount
          currencyCode
        }
        totalCost {
          amount
          currencyCode
        }
      }
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/InventoryPurchaseOrder/884380239"
}'

Direct API Access

const response = await fetch('shopify:admin/api/unstable/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query InventoryPurchaseOrder($id: ID!) {
        inventoryPurchaseOrder(id: $id) {
          id
          name
          status
          referenceName
          currency
          dateCreated
          orderedAt
          origin {
            supplier {
              name
            }
          }
          destination {
            name
            snapshottedAt
            location {
              id
              name
            }
          }
          lineItems(first: 10) {
            nodes {
              id
              title
              variantTitle
              supplierSku
              totalQuantity
              unitCost {
                amount
                currencyCode
              }
              totalCost {
                amount
                currencyCode
              }
            }
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/InventoryPurchaseOrder/884380239"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"id": "gid://shopify/InventoryPurchaseOrder/884380239"

}

Response

JSON

{

"inventoryPurchaseOrder": {

"id": "gid://shopify/InventoryPurchaseOrder/884380239",

"name": "PO-1001",

"status": "ORDERED",

"referenceName": "SNOWDEVIL-ERP-420",

"currency": "CAD",

"dateCreated": "2019-08-19T00:00:00Z",

"orderedAt": "2019-08-20T00:00:00Z",

"origin": {

"supplier": {

"name": "Vans"

}

"destination": {

"name": "Ottawa Store",

"snapshottedAt": "2019-08-19T00:00:00Z",

"location": {

"id": "gid://shopify/Location/346779380",

"name": "Ottawa Store"

}

"lineItems": {

"nodes": [

{

"id": "gid://shopify/InventoryPurchaseOrderLineItem/387823291",

"title": "Element",

"variantTitle": "151cm",

"supplierSku": "snowboard-inc-element-151",

"totalQuantity": 10,

"unitCost": {

"amount": "10.0",

"currencyCode": "CAD"

"totalCost": {

"amount": "107.0",

"currencyCode": "CAD"

}

{

"id": "gid://shopify/InventoryPurchaseOrderLineItem/593108211",

"title": "Element",

"variantTitle": "151cm",

"supplierSku": "snowboard-inc-element-151",

"totalQuantity": 10,

"unitCost": {

"amount": "10.0",

"currencyCode": "CAD"

"totalCost": {

"amount": "107.0",

"currencyCode": "CAD"

}

]

}