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": [
        "fac40015-343a-475a-855f-cf29cd715bf0",
        "3b942128-f26d-4661-bfc9-85056e1a3bd3",
        "ed89fb2f-b9e8-4243-9ed7-b216f98b5ff8",
        "9da7b441-432b-4274-8936-758b0099ada0"
    ]
}

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
oiQ1JVTkNIVElNRSIsInJzR3VpZCI6IjE4YzQ5YWJlLWFlODItNGFlYy04ND
M1LWJhYTRjMjVlYTY2MiIsInNjb3BlIjpbImxWQiOlsidG9hc3QiXSwibmFt
aW5nQXV0aGhYm9yIiwib3JkZXJzIiwidXNlcm1nbXQiXSwiZXhwIjoxNDg0M
zg5ODUwLCJqdGkiOiJlMDYzZjJkMy1jNGYyLTRiZjItODJmNi01MTg1NWMzZ
DAxM2YiLCJjbGllbnRfaWQiOiJjcnVuY2h0aW1lIn0.X1_0y9Hzj5F9gdOw2
o6VSYTyZwooAJiFMDmNakbZrtiUdYwLzuLwLpCMQzX5pKYtOqDUz_cetGJL3
txKL1L-K2j1Enoq8An8hEM6e8J0KdAiwrYFO3W3CmWedaoz95K9ghNZVCs28
Td2Sp3Ix3fObxbrvanocx9_OT8S9uM8hdSXmBI_ykTWvOVgK4hO24V3DJy4b
9bz1FtgOvrClhELxCe8dJy7jiwAR60xczlCF5rna98RMLN6zY4ffjmljKFZ6
QV0KkVppWjEiJn7oFHiIylCX1sSg7sddrGatj0xJzts3GJ8u8_lryUNHaEvJ
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
https://[toast-api-hostname]/stock/v1/inventory/search

1

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.

2

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

3

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

[1
    {
        "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
    }
]

1

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

2

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

3

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

4

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.

5

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.