This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Searching Inventory For Specific Menu Items

To retrieve inventory information for a list of menu items, you send a POST request to the /inventory/search endpoint. The request must include a message body that consists of an InventorySearchRequest object with a guids value that contains a list of menu item GUIDs to search for.

The following example shows the message body for a POST request to the /inventory/search endpoint.

JSON Message Body Content to Search Inventory By Menu Items

    "guids": [

The resource returns a JSON array of MenuItemInventory objects containing inventory information for the requested menu items. Inventory information is returned for all menu items on the list, regardless of their inventory status (QUANTITY, OUT_OF_STOCK, or IN_STOCK).

When using the /inventory/search endpoint, the MenuItemInventory object includes an itemGuidValidity value that indicates whether the menu item GUID is valid or not. A menu item GUID is invalid if it does not exist or has been archived at the restaurant being queried. itemGuidValidity is set to VALID if the menu item GUID is valid or INVALID if the menu item GUID is invalid. If a menu item GUID is invalid, the status for that menu item is set to OUT_OF_STOCK.

Also, if a valid menu item went out of stock and then came back in stock, its inventory status will be returned as IN_STOCK.

The following example curl command sends a POST request to the /inventory/search endpoint.

Search Inventory By Menu Items

curl -X POST \
-H "Authorization: Bearer eyJzI1NiJ9hbGciOiJSU.eyJhd9yaXR5Ij
dWq4Yzwo007AMgxjH9d241Y-g" \
-H "Toast-Restaurant-External-ID: 4622e7a9-b4be-3fef-9220-b3dad273e0b4" \1
-H "Content-Type: application/json" \2
-d @my-item-search-data.json \3


Use the Toast-Restaurant-External-ID request parameter to specify the GUID of the restaurant from which you want to retrieve menu item inventories by status. The GUID must be for an individual restaurant location, not the GUID for a restaurant group or management group.


Specify the data type of the message body in the Content-Type header field. The value must be application/json.


Include the menu item list in the message body of the POST request. This example curl command sends message body data from the contents of the my-item-search-data.json file.

The following example shows the JSON response data for a POST request to the /inventory/search resource.

Search Inventory By Menu Items Response Data

        "guid": "fac40015-343a-475a-855f-cf29cd715bf0",2
        "itemGuidValidity": "VALID",
        "status": "IN_STOCK",3
        "quantity": null
        "guid": "3b942128-f26d-4661-bfc9-85056e1a3bd3",
        "itemGuidValidity": "VALID",
        "status": "QUANTITY",
        "quantity": 100.04
        "guid": "ed89fb2f-b9e8-4243-9ed7-b216f98b5ff8",
        "itemGuidValidity": "INVALID",5
        "status": "OUT_OF_STOCK",
        "quantity": null


The GET request returns a JSON array of menu item inventory objects for the requested menu items.


The guid value contains the unique Toast POS identifier for the menu item.


The status value is one of QUANTITY, OUT_OF_STOCK, or IN_STOCK.


The quantity value indicates the amount of stock remaining for menu items with an inventory status of QUANTITY, and is null for OUT_OF_STOCK and IN_STOCK menu items.


An itemGuidValidity of INVALID indicates that the menu item GUID does not exist at the restaurant being queried or it has been archived. The status of INVALID menu item GUIDs is always OUT_OF_STOCK.