InventoryLevel

Version 2019-10

An inventory level represents the available quantity of an inventory item at a specific location.

Each inventory level belongs to one inventory item and has one location. For every location where an inventory item is available, there's an inventory level that represents the inventory item's quantity at that location:

Inventory levels and fulfillment service locations

A fulfillment service location has a 1:1 relationship with a third-party fulfillment service. When an app creates a new fulfillment service on a store, Shopify automatically creates a location that's associated with that fulfillment service. The FulfillmentService resource has a location_id property, which identifies the associated location.

An inventory item connected to a fulfillment service location can't be connected to any other locations at the same time:

Connecting an inventory item to a fulfillment service location

When you work with items that have been or will be connected a fulfillment location, you should include "relocate_if_necessary": true in the body of the request. There are two situations where you might do this:

  • connecting an inventory item to a fulfillment service location and disconnecting it from all standard locations
  • connecting an inventory item to one or more standard locations and disconnecting it from a fulfillment service location

If relocate_if_necessary is true, then all inventory for the item is relocated to the new location and disconnected from any other locations. If a fulfillment service location is involved but relocate_if_necessary is false, then the connection will fail. If no fulfillment service is involved, then the property is ignored and no inventory is relocated.

Setting the inventory level at a fulfillment service location

When you set inventory for a location, the inventory item is connected to the location if they are not already connected. If the item has been or will be connected to a fulfillment service location, then you should include "disconnect_if_necessary": true in the body of the request. There are two situations where you might do this:

  • setting inventory for an inventory item at a fulfillment service location when the item is already connected to one or more standard locations
  • setting inventory for an inventory item at a standard location when the item is already connected to a fulfillment service location

The inventory at the new location is set to the value of the available property. The inventory for other locations is set to 0 and the locations are disconnected from the inventory item.

If disconnect_if_necessary is set to false when you set inventory at a location and a fulfillment service location is involved, then the action will fail. If no fulfillment service location is involved, then this property is ignored.

What you can do with InventoryLevel

The Shopify API lets you do the following with the InventoryLevel resource. More detailed versions of these general actions may be available:

InventoryLevel properties

available
"available": 6

The quantity of inventory items available for sale. Returns null if the inventory item is not tracked.

inventory_item_id
read-only
"inventory_item_id": 450789469

The ID of the inventory item that the inventory level belongs to.

location_id
"location_id": 40642626

The ID of the location that the inventory level belongs to. To find the ID of the location, use the Location resource.

updated_at
read-only
"updated_at": "2012-08-24T14:01:47-04:00"

The date and time (ISO 8601 format) when the inventory level was last modified.

Endpoints

GET /admin/api/2019-10/inventory_levels.json

Retrieves a list of inventory levels.

You must include inventory_item_ids, location_ids, or both as filter parameters.

Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

inventory_item_ids

A comma-separated list of inventory item IDs.

(maximum: 50)
location_ids

A comma-separated list of location IDs. To find the ID of a location, use the Location resource.

(maximum: 50)
limit

The maximum number of results to show.

(default: 50, maximum: 250)
updated_at_min

Show inventory levels updated at or after date (format: 2019-03-19T01:21:44-04:00).

Retrieving inventory levels without specifying location_ids or inventory_item_ids fails and returns an error

GET /admin/api/2019-10/inventory_levels.json
View Response
HTTP/1.1 422 Unprocessable Entity

Retrieve inventory levels for the specified inventory items and locations

GET /admin/api/2019-10/inventory_levels.json?inventory_item_ids=808950810,39072856&location_ids=905684977,487838322
View Response
HTTP/1.1 200 OK
{
  "inventory_levels": [
    {
      "inventory_item_id": 808950810,
      "location_id": 487838322,
      "available": 9,
      "updated_at": "2021-07-01T13:58:02-04:00",
      "admin_graphql_api_id": "gid://shopify/InventoryLevel/690933842?inventory_item_id=808950810"
    },
    {
      "inventory_item_id": 39072856,