InventoryLevel

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

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:

Location types

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
"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
"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/inventory_levels.json

Retrieves a list of inventory levels.

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

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)
page

The page of results to show.

limit

The maximum number of results to show.

(default: 50) (maximum: 250)

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

GET /admin/inventory_levels.json
View Response
HTTP/1.1 422 Unprocessable Entity

Retrieve inventory levels for the specified inventory items and locations

GET /admin/inventory_levels.json?inventory_item_ids=808950810,39072856&location_ids=905684977,487838322
View Response
HTTP/1.1 200 OK
{
  "inventory_levels": [
    {
      "inventory_item_id": 39072856,
      "location_id": 487838322,
      "available": 27,
      "updated_at": "2018-05-07T15:33:38-04:00"
    },
    {
      "inventory_item_id": 808950810,
      "location_id": 905684977,
      "available": 1,
      "updated_at": "2018-05-07T15:33:38-04:00"
    },
    {
      "inventory_item_id": 808950810,
      "location_id": 487838322,
      "available": 9,
      "updated_at": "2018-05-07T15:33:38-04:00"
    },
    {
      "inventory_item_id": 39072856,
      "location_id": 905684977,
      "available": 3,
      "updated_at": "2018-05-07T15:33:38-04:00"
    }
  ]
}

Retrieve inventory levels for a single inventory item

GET /admin/inventory_levels.json?inventory_item_ids=808950810
View Response
HTTP/1.1 200 OK
{
  "inventory_levels": [
    {
      "inventory_item_id": 808950810,
      "location_id": 905684977,
      "available": 1,
      "updated_at": "2018-05-07T15:33:38-04:00"
    },
    {
      "inventory_item_id": 808950810,
      "location_id": 487838322,
      "available": 9,
      "updated_at": "2018-05-07T15:33:38-04:00"
    }
  ]
}

Retrieve inventory levels at a single location

GET /admin/inventory_levels.json?location_ids=905684977
View Response
HTTP/1.1 200 OK
{
  "inventory_levels": [
    {
      "inventory_item_id": 808950810,
      "location_id": 905684977,
      "available": 1,
      "updated_at": "2018-05-07T15:33:38-04:00"
    },
    {
      "inventory_item_id": 49148385,
      "location_id": 905684977,
      "available": 2,
      "updated_at": "2018-05-07T15:33:38-04:00"
    },
    {
      "inventory_item_id": 457924702,
      "location_id": 905684977,
      "available": 4,
      "updated_at": "2018-05-07T15:33:38-04:00"
    },
    {
      "inventory_item_id": 39072856,
      "location_id": 905684977,
      "available": 3,
      "updated_at": "2018-05-07T15:33:38-04:00"
    }
  ]
}
POST /admin/inventory_levels/adjust.json

Adjusts the inventory level of an inventory item at a single location

inventory_item_id
required

The ID of the inventory item.

location_id
required

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

available_adjustment
required

The amount to adjust the available inventory quantity. Send negative values to subtract from the current available quantity. For example, "available_adjustment": 2 increases the current available quantity by 2, and "available_adjustment": -3decreases the current available quantity by 3.

Adjust the available quantity of an inventory item by 5 at a single location

POST /admin/inventory_levels/adjust.json
{
  "location_id": 905684977,
  "inventory_item_id": 808950810,
  "available_adjustment": 5
}
View Response
HTTP/1.1 200 OK
{
  "inventory_level": {
    "inventory_item_id": 808950810,
    "location_id": 905684977,
    "available": 6,
    "updated_at": "2018-05-07T15:51:26-04:00"
  }
}

Adjusting inventory levels at a non-existent location fails and returns an error

POST /admin/inventory_levels/adjust.json
{
  "location_id": 905684977,
  "inventory_item_id": 808950810,
  "available_adjustment": 5
}
View Response
HTTP/1.1 404 Not Found
{
  "errors": "Not Found"
}

Adjusting inventory levels for an inventory item that is untracked fails and returns an error

POST /admin/inventory_levels/adjust.json
{
  "location_id": 905684977,
  "inventory_item_id": 808950810,
  "available_adjustment": 5
}
View Response
HTTP/1.1 422 Unprocessable Entity
DELETE /admin/inventory_levels.json
Deletes an inventory level of an inventory item at a location. Deleting an inventory level for an inventory item removes that item from the specified location. Every inventory item must have at least one inventory level. To move inventory to another location, first connect the inventory item to another location, and then delete the previous inventory level.
inventory_item_id
required

The ID for the inventory item.

location_id
required

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

Delete an inventory level

DELETE /admin/inventory_levels.json?inventory_item_id=808950810&location_id=905684977
View Response
HTTP/1.1 204 No Content
POST /admin/inventory_levels/connect.json

Connects an inventory item to a location by creating an inventory level at that location.

When connecting inventory items to locations, it's important to understand the rules around fulfillment service locations.

Important

Multi-location inventory is coming soon, but it is not yet possible to connect inventory items to multiple locations. To learn more about prepairing your app for multi-location inventory, see Migrating to multi-location inventory.

inventory_item_id
required

The ID of the inventory item.

location_id
required

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

relocate_if_necessary

Whether inventory for any previously connected locations will be relocated. This property is ignored when no fulfillment service location is involved. For more information, see Inventory levels and fulfillment service locations.

(default: false)

Connect an inventory item to a location

POST /admin/inventory_levels/connect.json
{
  "location_id": 905684977,
  "inventory_item_id": 447654529
}
View Response
HTTP/1.1 201 Created
{
  "inventory_level": {
    "inventory_item_id": 447654529,
    "location_id": 905684977,
    "available": 0,
    "updated_at": "2018-05-07T15:51:28-04:00"
  }
}

Connecting an inventory item to a non-existent location fails and returns an error

POST /admin/inventory_levels/connect.json
{
  "location_id": 123,
  "inventory_item_id": 447654529
}
View Response
HTTP/1.1 404 Not Found
{
  "errors": "Not Found"
}

Connecting an inventory item to a fulfillment service location without "relocate_if_necessary": true fails with a 422 error

POST /admin/inventory_levels/connect.json
{
  "location_id": 48752903,
  "inventory_item_id": 808950810
}
View Response
HTTP/1.1 422 Unprocessable Entity

Connecting an inventory item to a location when the store isn't multi-location enabled fails and with a 403 error

POST /admin/inventory_levels/connect.json
{
  "location_id": 905684977,
  "inventory_item_id": 447654529
}
View Response
HTTP/1.1 403 Forbidden
POST /admin/inventory_levels/set.json
Sets the inventory level for an inventory item at a location. If the specified location is not connected, it will be automatically connected first. When connecting inventory items to locations, it's important to understand the rules around fulfillment service locations.

Important

Multi-location inventory is coming soon, but it is not yet possible to connect inventory items to multiple locations. To learn more about prepairing your app for multi-location inventory, see Migrating to multi-location inventory.

inventory_item_id
required

The ID for the inventory item.

location_id
required

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

available
required

Sets the available inventory quantity.

disconnect_if_necessary

Whether inventory for any previously connected locations will be set to 0 and the locations disconnected. This property is ignored when no fulfillment service is involved. For more information, see Inventory levels and fulfillment service locations.

(default: false)

Set the available inventory at a location

POST /admin/inventory_levels/set.json
{
  "location_id": 905684977,
  "inventory_item_id": 808950810,
  "available": 42
}
View Response
HTTP/1.1 200 OK
{
  "inventory_level": {
    "inventory_item_id": 808950810,
    "location_id": 905684977,
    "available": 42,
    "updated_at": "2018-05-07T15:51:30-04:00"
  }
}

Setting an inventory item to a fulfillment service without "disconnect_if_necessary": true fails with a 422 error

POST /admin/inventory_levels/set.json
{
  "location_id": 61629186,
  "inventory_item_id": 808950810,
  "available": 42
}
View Response
HTTP/1.1 422 Unprocessable Entity