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.

This section provides reference information about the endpoints and data types of the Toast stock API. For more information about using the stock API and code examples, see Inventory. For general information about working with Toast APIs, see API overview.

Stock API

Base URL: /stock/v1, Version: 1.0.0

The stock API lets you retrieve and update inventory information for a restaurant's menu items and modifiers.

Note: Modifiers are supported by an underlying menu item, called the modifier's item reference. In this reference, the term "menu item" is used to generically refer to both standalone menu items and modifier item references, because the same data is used for both. For more information, see Understanding a modifier option's item reference.

You can use the stock API to:

  • Get all inventory information for a restaurant.
  • Get inventory information for a list of menu items.
  • Get inventory information for a specific status of the menu items (such as all menu items that are out of stock).
  • Update inventory information for a list of menu items.

Default request content-types: application/json
Default response content-types: application/json
Schemes: https

Summary

Path Operation Description
/inventory GET

Get menu item inventory for a restaurant
/inventory/search POST

Get inventory information for specific menu items
/inventory/update PUT

Updates inventory information for specific menu items

Paths

Get menu item inventory for a restaurant

GET /inventory

Returns inventory information for all menu items that have an OUT_OF_STOCK or QUANTITY status.

Inventory information is not returned for menu items with an IN_STOCK status, because they are not considered at risk for going out of stock.

To restrict the menu items in the response to either OUT_OF_STOCK or QUANTITY stock status, use the status query parameter.
Toast-Restaurant-External-ID

The Toast GUID of the restaurant queried for inventory information.

 header string
status

Limits the items in the response to those items with the specified stock status. Values are:

  • OUT_OF_STOCK- Returns all menu items that have the OUT_OF_STOCK stock status.

  • QUANTITY - Returns all menu items that have the QUANTITY stock status.

 query string

application/json

200 OK

Successful operation

MenuItemInventory
404 Not Found

Restaurant did not have any inventory information.

Get inventory information for specific menu items

POST /inventory/search

Returns inventory information for a list of menu items.

The request must include a message body that contains an InventorySearchRequest object with one or both of these values:

  • AmultiLocationIds value that contains an array of menu item multi-location IDs to search for.

  • A guids value that contains an array of menu item GUIDs to search for.

For information on these two identifier types, see Toast identifiers.

Uses default content-types: application/json

An InventorySearchRequest object containing identifiers for the menu items to include in the search.

InventorySearchRequest
Toast-Restaurant-External-ID

The Toast GUID of the restaurant queried for inventory information.

 header string

application/json

200 OK

Successful operation

MenuItemInventory
404 Not Found

One of the specified menu items does not have inventory information.

Updates inventory information for specific menu items

PUT /inventory/update

Updates inventory information for a list of menu items.

Uses default content-types: application/json

An array of MenuItemInventoryUpdate objects for the menu items to be updated, with the following values:

  • An identifier for the menu item to be updated. This may be either the menu item's multiLocationId or its guid. See Toast identifiers for more information on these two identifier types.

  • The status for the menu item. Must be one of the following:

    • IN_STOCK
    • OUT_OF_STOCK
    • QUANTITY

  • For menu items with a status of QUANTITY, you must also provide a quantity value that is a double greater than 0 (such as 0.5, 7.0, or 10.75). Do not include a quantity value for menu items with a status of IN_STOCK or OUT_OF_STOCK.

MenuItemInventory
Toast-Restaurant-External-ID

The Toast GUID of the restaurant whose inventory information will be updated.

 header string

application/json

200 OK

Successful operation

MenuItemInventoryUpdate
404 Not Found

One or more of the specified menu items could not be found. The entire update request fails. The GUIDs for the menu items that couldn't be found are provided in the message value of the response's message body.

Schema definitions

InventorySearchRequest: object

Contains search parameters for retrieving menu item inventory information.

guids: string[]

An array of menu item GUIDs. The /inventory/search endpoint tries to find menu items with matching GUIDs.

string (uuid)
multiLocationIds: string[]

An array of menu item multi-location IDs. The /inventory/search endpoint tries to find menu items with matching multi-location IDs.

See Toast identifiers for more information on multi-location IDs.

string
versionIds: string[]

For future use.

string (uuid)

MenuItemInventory: object

Contains the stock status and quantity information for a menu item.

guid: string (uuid)

The unique GUID assigned to the menu item by the Toast platform.

itemGuidValidity: string , x ∈ { VALID , INVALID }

This value, which is only included in the MenuItemInventory object when the /inventory/search endpoint is queried, indicates whether the menu item GUID is valid or not. A menu item GUID is not valid if the menu item does not exist at the restaurant being queried or it has been archived. The itemGuidValidity value can be:

  • VALID - The menu item exists at the restaurant being queried and it has not been archived.

  • INVALID - The menu item either does not exist at the restaurant being queried or it has been archived.

status: string , x ∈ { IN_STOCK , QUANTITY , OUT_OF_STOCK }

The inventory status of the menu item. The status value can be:

  • IN_STOCK - The menu item is in stock in the restaurant.

  • QUANTITY - The menu item is in limited supply. The amount of remaining items is indicated by the quantity value.

  • OUT_OF_STOCK - The menu item is no longer in stock and cannot be selected for an order.

quantity: number (double)

Contains the amount of stock remaining when the menu item status is QUANTITY.

This value is null for menu items that have a stock staus of IN_STOCK or OUT_OF_STOCK.

multiLocationId: string

A consistent identifier that applies to all versions of a menu item that is shared across locations.

See Toast identifiers for more information.

versionId: string (uuid)

For future use.

MenuItemInventoryUpdate: object

Contains the stock status and quantity information for a menu item.

guid: string (uuid)

The unique GUID assigned to the menu item by the Toast platform.

status: string , x ∈ { IN_STOCK , QUANTITY , OUT_OF_STOCK }

The inventory status of the menu item. The status value can be:

  • IN_STOCK - The menu item is in stock in the restaurant.

  • QUANTITY - The menu item is in limited supply. The amount of remaining items is indicated by the quantity value.

  • OUT_OF_STOCK - The menu item is no longer in stock and cannot be selected for an order.

quantity: number (double)

Contains the amount of stock remaining when the menu item status is QUANTITY.

This value is null for menu items that have a stock staus of IN_STOCK or OUT_OF_STOCK.

multiLocationId: string

A consistent identifier that applies to all versions of a menu item that is shared across locations.

See Toast identifiers for more information.

versionId: string (uuid)

For future use.