Skip to main content

Purchase Order Read API

You can now read purchase orders through the inventoryPurchaseOrder and inventoryPurchaseOrders queries in GraphQL Admin API version 2026-10 and later. This public release lets apps read purchase order details, line items, supplier snapshots, and linked inventory transfers without enrolling shops in the physical inventory feature preview.

Apps using the preview's read_inventory access must obtain purchase order read access.

What changed

Previously, public apps read purchase orders only through the unstable preview. The 2026-10 GraphQL Admin API now exposes:

  • inventoryPurchaseOrder to retrieve a purchase order by ID, and inventoryPurchaseOrders to retrieve a paginated list.
  • Purchase order details and line items, including the supplier name captured in origin.supplierName.
  • A paginated transfers connection returning the linked InventoryTransfer objects. Reading these objects also requires read_inventory_transfers access.

InventoryPurchaseOrder.referenceName is not part of the public 2026-10 API. If your preview query selects it, remove that selection before moving to 2026-10.

This is a read-only release. Purchase order mutations are not included. Existing user permissions continue to apply.

Who's affected

  • Apps adopting purchase order reads: Request read_inventory_purchase_orders. Neither API beta access nor shop preview enrollment is required for these reads.
  • Existing preview integrations: read_inventory alone no longer authorizes purchase order reads, including on unstable. Obtain read_inventory_purchase_orders before relying on the released behavior. Keep read_inventory if your app still needs it for other inventory resources.
  • Apps already granted purchase order access: No additional purchase order scope request is needed if the installation already has read_inventory_purchase_orders or write_inventory_purchase_orders, which includes read access. Check your queries against the released field names and types.

Versions 2026-07 and earlier do not gain these public queries. Apps that don't read purchase orders don't need to make changes.

What to do

  1. Update your app's requested scopes. Add read_inventory_purchase_orders, and add read_inventory_transfers if you need the transfers connection. Preserve any other scopes your app still needs.
  2. Obtain the new grants. Deploy the configuration changes and complete your app's scope approval flow for existing installations. Changing the requested scopes alone does not grant access. Verify the installation's granted scopes through currentAppInstallation.accessScopes.
  3. Update and test your queries. Target /admin/api/2026-10/graphql.json, and use the supplier and transfer fields shown below. If you integrate before October 1, 2026, 2026-10 is a release candidate: use it for testing rather than production.
  4. Check the result on a development store. Use a store with a purchase order and a linked transfer. Confirm the query returns those records without schema-validation or ACCESS_DENIED errors. Check both access scopes and the acting user's permissions if access is denied.

For a Shopify CLI app that needs both purchase orders and their linked transfers, include these scopes in shopify.app.toml:

[access_scopes]
scopes = "read_inventory_purchase_orders,read_inventory_transfers"

Merge these values with your existing scope list rather than replacing it. Apps that already hold the corresponding write scopes don't need to request redundant read scopes.

This example reads the first five purchase orders, with up to five line items and five linked transfers per purchase order:

query PurchaseOrders {
inventoryPurchaseOrders(first: 5) {
nodes {
id
name
status
origin {
supplierName
}
lineItems(first: 5) {
nodes {
id
title
}
}
transfers(first: 5) {
nodes {
id
name
}
}
}
}
}

Paginate each connection to retrieve additional records. If your app doesn't need transfers, omit that selection and the additional transfer scope.

Related docs

Was this page helpful?