# InventoryLevel

An inventory level represents the quantities of an inventory item for a location.

Each inventory level belongs to one inventory item and has one location. For every location where an inventory item can be stocked, there's an inventory level that represents the inventory item's quantities relating to that location.

{{ '/api/reference/inventory.png' | image }}

Before you begin updating inventory, it's helpful to understand the relationships between the inventory resources:

How an order affects inventory

When a product variant that Shopify tracks is included in an order, Shopify decrements the inventory for that variant. Shopify doesn't know which location the item will be fulfilled from, so Shopify decrements the inventory level at the location that has the lowest ID.

When an order is fulfilled, the fulfillment includes the ID of the location where the fulfillment is taking place. Shopify checks whether the fulfillment location matches the original location where stock was decremented, and then adjusts the inventory if necessary:

Example: Inventory adjustments for a simple order

An online store uses two warehouses to stock product inventory: one in Los Angeles (ID: 6884556842), and one in New York (ID: 13968834616). One of the store's products is a hat that's stocked at both locations with the following inventory levels:

A customer places an order for a hat. The Los Angeles location has the lowest ID, so Shopify decrements the item's inventory level at that location:

The order is actually fulfilled from the New York location. When the fulfillment is created, it includes the ID for the New York location. Shopify compares the fulfillment location ID to the original location and finds that they're different. Shopify then increments the inventory level at the Los Angeles location, and decrements the inventory level at the New York 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:

{{ '/api/reference/location-types.png' | image }}

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:

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:

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.

## Resource Properties ### InventoryLevel * available: The available quantity of an inventory item at the inventory level's associated location. Returns null if the inventory item is not tracked. * Type: x-string * Example: 6 * inventory_item_id: The ID of the inventory item associated with the inventory level. To find the ID of an inventory item, use the Inventory Item resource * Type: x-string * Example: 450789469 * location_id: The ID of the location that the inventory level belongs to. To find the ID of the location, use the Location resource * Type: x-string * Example: 40642626 * updated_at: The date and time (ISO 8601 format) when the inventory level was last modified. * Type: x-string * Example: "2012-08-24T14:01:47-04:00" ## Retrieves a list of inventory levels

Retrieves a list of inventory levels.

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

Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

### Endpoint /admin/api/#{api_version}/inventory_levels.json?location_ids=655441491 (GET) ### Parameters * api_version (required): * inventory_item_ids: A comma-separated list of inventory item IDs. To find the ID of an inventory item, use the Inventory Item resource * limit: The maximum number of results to show. * location_ids: A comma-separated list of location IDs. To find the ID of a location, use the Location resource * updated_at_min: Show inventory levels updated at or after date (format: 2019-03-19T01:21:44-04:00). ### Responses #### 200 Retrieves a list of inventory levels Examples: ##### Retrieve inventory levels at a single location Request: ``` GET /admin/api/unstable/inventory_levels.json ``` Response: ``` HTTP/1.1 200 OK {"inventory_levels":[{"inventory_item_id":49148385,"location_id":655441491,"available":2,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=49148385"},{"inventory_item_id":808950810,"location_id":655441491,"available":1,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=808950810"},{"inventory_item_id":457924702,"location_id":655441491,"available":4,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=457924702"},{"inventory_item_id":39072856,"location_id":655441491,"available":3,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=39072856"}]} ``` ##### Retrieve inventory levels for a single inventory item Request: ``` GET /admin/api/unstable/inventory_levels.json ``` Response: ``` HTTP/1.1 200 OK {"inventory_levels":[{"inventory_item_id":808950810,"location_id":487838322,"available":9,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/548380009?inventory_item_id=808950810"},{"inventory_item_id":808950810,"location_id":655441491,"available":1,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=808950810"}]} ``` ##### Retrieve inventory levels for the specified inventory items and locations Request: ``` GET /admin/api/unstable/inventory_levels.json ``` Response: ``` HTTP/1.1 200 OK {"inventory_levels":[{"inventory_item_id":808950810,"location_id":487838322,"available":9,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/548380009?inventory_item_id=808950810"},{"inventory_item_id":39072856,"location_id":487838322,"available":27,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/548380009?inventory_item_id=39072856"},{"inventory_item_id":808950810,"location_id":655441491,"available":1,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=808950810"},{"inventory_item_id":39072856,"location_id":655441491,"available":3,"updated_at":"2025-01-08T16:01:01-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=39072856"}]} ``` #### 422 Retrieves a list of inventory levels Examples: ##### Retrieving inventory levels without specifying location_ids or inventory_item_ids fails and returns an error Request: ``` GET /admin/api/unstable/inventory_levels.json ``` Response: ``` HTTP/1.1 422 Unprocessable Entity ``` ## Adjusts the inventory level of an inventory item at a location

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

### Endpoint /admin/api/#{api_version}/inventory_levels/adjust.json (POST) ### Parameters * api_version (required): * 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. * 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 ### Responses #### 200 Adjusts the inventory level of an inventory item at a location Examples: ##### Adjust the available quantity of an inventory item by 5 at a single location Request: ``` POST /admin/api/unstable/inventory_levels/adjust.json {"location_id":655441491,"inventory_item_id":808950810,"available_adjustment":5} ``` Response: ``` HTTP/1.1 200 OK {"inventory_level":{"inventory_item_id":808950810,"location_id":655441491,"available":6,"updated_at":"2025-01-08T16:01:57-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=808950810"}} ``` #### 404 Adjusts the inventory level of an inventory item at a location Examples: ##### Adjusting inventory levels at a non-existent location fails and returns an error Request: ``` POST /admin/api/unstable/inventory_levels/adjust.json {"location_id":655441491,"inventory_item_id":808950810,"available_adjustment":5} ``` Response: ``` HTTP/1.1 404 Not Found {"errors":"Not Found"} ``` #### 422 Adjusts the inventory level of an inventory item at a location Examples: ##### Adjusting inventory levels for an inventory item that is untracked fails and returns an error Request: ``` POST /admin/api/unstable/inventory_levels/adjust.json {"location_id":655441491,"inventory_item_id":808950810,"available_adjustment":5} ``` Response: ``` HTTP/1.1 422 Unprocessable Entity ``` ## Deletes an inventory level from a location 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. ### Endpoint /admin/api/#{api_version}/inventory_levels.json?inventory_item_id=808950810&location_id=655441491 (DELETE) ### Parameters * api_version (required): * 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 ### Responses #### 204 Deletes an inventory level from a location Examples: ##### Delete an inventory level Request: ``` DELETE /admin/api/unstable/inventory_levels.json ``` Response: ``` HTTP/1.1 204 No Content ``` ## Connects an inventory item to a location

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.

### Endpoint /admin/api/#{api_version}/inventory_levels/connect.json (POST) ### Parameters * api_version (required): * 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, refer to Inventory levels and fulfillment service locations. ### Responses #### 201 Connects an inventory item to a location Examples: ##### Connect an inventory item to a location Request: ``` POST /admin/api/unstable/inventory_levels/connect.json {"location_id":844681632,"inventory_item_id":457924702} ``` Response: ``` HTTP/1.1 201 Created {"inventory_level":{"inventory_item_id":457924702,"location_id":844681632,"available":0,"updated_at":"2025-01-08T16:01:50-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/844681632?inventory_item_id=457924702"}} ``` #### 422 Connects an inventory item to a location Examples: ##### Connecting an inventory item to a fulfillment service location without "relocate_if_necessary": true fails with a 422 error when permits_sku_sharing is false Request: ``` POST /admin/api/unstable/inventory_levels/connect.json {"location_id":611870435,"inventory_item_id":808950810} ``` Response: ``` HTTP/1.1 422 Unprocessable Entity {"errors":["An item cannot be active at more than one location if one of them is a fulfillment service location."]} ``` #### 404 Connects an inventory item to a location Examples: ##### Connecting an inventory item to a non-existent location fails and returns an error Request: ``` POST /admin/api/unstable/inventory_levels/connect.json {"location_id":123,"inventory_item_id":457924702} ``` Response: ``` HTTP/1.1 404 Not Found {"errors":"Not Found"} ``` ## Sets the inventory level for an inventory item at a location 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. ### Endpoint /admin/api/#{api_version}/inventory_levels/set.json (POST) ### Parameters * api_version (required): * available (required): Sets the available inventory quantity. * inventory_item_id (required): The ID of the inventory item associated with the inventory level. To find the ID of the inventory item, use the Inventory Item resource * 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 * 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, refer to Inventory levels and fulfillment service locations. ### Responses #### 200 Sets the inventory level for an inventory item at a location Examples: ##### Set the available inventory at a location Request: ``` POST /admin/api/unstable/inventory_levels/set.json {"location_id":655441491,"inventory_item_id":808950810,"available":42} ``` Response: ``` HTTP/1.1 200 OK {"inventory_level":{"inventory_item_id":808950810,"location_id":655441491,"available":42,"updated_at":"2025-01-08T16:01:59-05:00","admin_graphql_api_id":"gid://shopify/InventoryLevel/655441491?inventory_item_id=808950810"}} ``` #### 422 Sets the inventory level for an inventory item at a location Examples: ##### Setting an inventory item to a fulfillment service without "disconnect_if_necessary": true fails with a 422 error Request: ``` POST /admin/api/unstable/inventory_levels/set.json {"location_id":611870435,"inventory_item_id":808950810,"available":42} ``` Response: ``` HTTP/1.1 422 Unprocessable Entity {"errors":["An item cannot be active at more than one location if one of them is a fulfillment service location."]} ```