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.
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 /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:
|
query | string |
application/json
- 200 OK
-
Successful operation
- 404 Not Found
-
Restaurant did not have any inventory information.
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:
A
multiLocationIds
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.
Toast-Restaurant-External-ID | The Toast GUID of the restaurant queried for inventory information. |
header | string |
application/json
- 200 OK
-
Successful operation
- 404 Not Found
-
One of the specified menu items does not have inventory information.
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 itsguid
. 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 aquantity
value that is a double greater than 0 (such as 0.5, 7.0, or 10.75). Do not include aquantity
value for menu items with astatus
ofIN_STOCK
orOUT_OF_STOCK
.
Toast-Restaurant-External-ID | The Toast GUID of the restaurant whose inventory information will be updated. |
header | string |
application/json
- 200 OK
-
Successful operation
- 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
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)
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. TheitemGuidValidity
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 thequantity
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
isQUANTITY
.This value is
null
for menu items that have a stock staus ofIN_STOCK
orOUT_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.
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 thequantity
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
isQUANTITY
.This value is
null
for menu items that have a stock staus ofIN_STOCK
orOUT_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.