Using kitchen fulfillment data -

Requirements

Before you can retrieve and use kitchen fulfillment data, you need:

Kitchen display system (KDS) devices in your kitchen.

Note

You need a minimum of one active KDS device to gather data. Toast support recommends more than one to gather data for multiple fulfillment levels.

An active subscription to Toast Restaurant Management Suite Pro or higher.

Note

If you make a request without the proper access, you’ll receive a 204 error.

For more information, see Getting kitchen fulfillment data.

Best practices

Recommended setup

To optimize your kitchen fulfillment data, Toast support recommends the following setup:

Schedule a daily export of data at the end of the business day. You can only export kitchen fulfillment data for a single business day at a time. Request and export the data at the end of the business day to avoid making multiple requests.
Retrieve historical data. Retrieve historical data instead of accumulating historical data for analysis. Historical kitchen fulfillment data is available starting on January 1, 2022.
Store the raw data for easier calculation. Toast support recommends creating new metrics from the initial values.
Create metrics when you first download the data. This avoids having to repeat and run the query each time the metric is used.

Maintaining data quality

Below is a list of common practices that can help maintain quality kitchen fulfillment data:

Fulfill items when they are completed. This helps keep accurate fulfillment times for each level of fulfillment.

For example, if an employee waits until the end of their shift to fulfill tickets, it can result in inflated ticket times. A ticket started at 10:05 AM and a ticket started at 2:00 PM, both fulfilled at 2:05 PM when an employee’s shift ends, results in a ticket fulfilled in four hours and another fulfilled in five minutes.
Use Recently fulfilled to look at recently fulfilled tickets. This keeps items and tickets to their original fulfillment times. If you use RECALL, the itemFulfilledAt time is reset to when the recalled ticket is fulfilled.

For example, if an employee wants to see the most recently fulfilled ticket, they can select Recently fulfilled to see tickets fulfilled within the time range set by Recently fulfilled timeframe. If an employee uses RECALL instead, the itemFulfilledAt time changes to when that recalled ticket is fulfilled. A ticket originally fulfilled at 9:30 AM that is recalled and then fulfilled again at 9:50 AM now has the new fulfillment time as 9:50 AM. If the ticket was fired at 9:26 AM, this changes the fulfillment time from four minutes to 24 minutes.
Be aware of items never fulfilled or voided in the middle of completion. Items never fulfilled at a particular fulfillment level do not have data for that fulfillment level. Similarly, voided items may be missing fulfillment information because it was not completed at all fulfillment levels. For example, if you do not fulfill an item at a prep station, but fulfill at the expediter, it will have fulfillment data for the expediter, but not for the prep station.

Understanding the kitchen fulfillment data

Each ItemFulfillment object represents the fulfillment of an item at one fulfillment level. If an item uses multiple prep stations, there is a separate ItemFulfillment object for each prep station at the prep station fulfillment level.

For example, a location uses two-level expediter fulfillment. A Classic Pizza item uses the Dough, Toppings, and Bake prep stations. An order containing this item is fulfilled at all levels, resulting in five ItemFulfillment objects:

Prep station level fulfillment at the Dough prep station.
Prep station level fulfillment at the Toppings prep station.
Prep station level fulfillment at the Bake prep station.
Expediter level fulfillment at the first-level expediter.
Expediter level fulfillment at the second-level expediter.

Using the associated fulfillment times for each ItemFulfillment object, you can determine how long an item spent at each station and how long an item spent in the kitchen overall.

Use selectionGuid to identify data for the same item in a specific order. You can use the accompanying selectionMenuItemGuid to identify which menu item it is.

Note

Toast support recommends using the selectionMenuItemGuid value instead of the selectionMenuItemName value to identify the menu item.

You can use additional values contained in the ItemFulfillment object to make additional observations. For example:

Use diningOptionBehavior and diningOptionName to determine differences in fulfillment times based on different dining options. For more information about dining options and dining behaviors, see Dining options.
Use orderSource to see whether some order sources take longer to prepare than others. An order source indicates the way that the order was placed. For more information, see Effect of order source on order validation and processes.
Use courseName to see whether courses are being timed consecutively or simultaneously. Courses are used to manage how tickets and items are fired to the kitchen for fulfillment. For an example of how courses work on KDS devices, see KDS workflow using courses.

Calculating fulfillment times

You can create three primary fulfillment times using your kitchen fulfillment data:

Item fulfillment times: This metric tells you how long it took for the kitchen to prepare an item.
Prep station fulfillment times: This metric tells you how long an item was worked on at a prep station. This can provide insight into prep station productivity.
Expediter fulfillment times: This metric tells you how long an item was waiting at the expediter station after being prepared before it was brought to guests. This can provide information about how long an item was waiting for other items in the order to be brought to guests.

Item fulfillment times

The item fulfillment time is calculated using the time when the item was fired to the kitchen and the time it was fulfilled at the highest fulfillment level. The fulfillment level is determined by the itemFulfillmentLevel, the highest of which depends on whether you use expediter KDS devices and, if you do, whether you use the Two-level fulfillment setting.

If you use only prep stations, filter itemFulfillmentLevel by 0, and use the most recent itemFulfilledAt time. If an item uses multiple prep stations, this represents the most recent fulfillment time at a prep station.
If you use a single expediter level, filter itemFulfillmentLevel by 1.
If you use two expediter levels (Two-level fulfillment is set to Two levels), filter itemFulfillmentLevel by 2.

Finding the highest fulfillment level ensures you’re using the most recent time an item was fulfilled.

For each object, find the ticketFiredAt and itemFulfilledAt values. itemFulfilledAt represents the time when the item was completed by the kitchen and ticketFiredAt represents when the ticket is fired to the kitchen. Both values use ISO 8601 format.

Note

The ticketFiredAt value does not change depending on the itemFulfillmentLevel value.

Use the time the item was fulfilled at the highest fulfillment level and subtract the time when the ticket was fired. The resulting value is how long the item was in the kitchen.

With itemFulfillmentLevel filtered by the highest fulfillment level, use the following equation:

itemFulfilledAt - ticketFiredAt

For example, you have Two-level fulfillment set to Two levels, meaning the highest level for fulfillment is the second-level expediter KDS device, so you filter itemFulfillmentLevel by 2.

One object includes:

ticketFiredAt with the value 2026-02-24T17:06:10Z
itemFulfilledAt with the value 2026-02-24T17:10:44Z

This means that on February 24, 2026, the ticket was fired at 05:06:10 PM and the item was fulfilled at the second-level expediter KDS device at 05:10:44 PM. The item fulfillment time in this case is four minutes and 34 seconds, or:

17:10:44 - 17:06:10 = 00:04:34

Using the item fulfillment time, you can determine which items take the longest to prepare, and whether the fulfillment time for an item changes depending on additional factors.

Prep station fulfillment times

The prep station fulfillment time is calculated using the time the item was sent to the kitchen and the time the item was fulfilled at the prep station fulfillment level. If you use start queue, you can calculate how long the item was actively worked on at a prep station using the time the item was started and when it was fulfilled at the prep station level.

Filter by the prep station fulfillment level, which is represented by an itemFulfillmentLevel value of 0.

Group the prepStationGuid values to look at fulfillment times for a single prep station.

Note

Toast support recommends using the prepStationGuid value instead of the prepStationName value to identify the prep station.

For each object, find ticketFiredAt and itemFulfilledAt. ticketFiredAt represents when the item was sent to the kitchen and itemFulfilledAt represents when the item was fulfilled at the prep station. Both values use ISO 8601 format.

Use the time the item was fulfilled at a prep station and subtract the time when the ticket was fired. The resulting value is how long the item was at a particular prep station.

Note

If you use multiple prep stations for an item, use the most recent itemFulfilledAt time to know how long the item spent at prep stations overall.

With itemFulfillmentLevel filtered by 0, use the following equation:

itemFulfilledAt - ticketFiredAt

For example, you have a Classic Pizza item that is sent to the Dough and Toppings prep stations. After filtering itemFulfillmentLevel by 0 and by the selectionGuid for the Classic Pizza item in a specific order, you have two objects: one for the Dough prep station and one for the Toppings prep station.

The object matching the Dough prep station prepStationGuid value includes:

ticketFiredAt with the value 2026-02-24T17:06:10Z
itemFulfilledAt with the value 2026-02-24T17:08:37Z

This means that on February 24, 2026, the ticket was fired at 05:06:10 PM and the item was fulfilled at the Dough prep station KDS device at 05:08:37 PM. The item fulfillment time at the Dough prep station is two minutes and 27 seconds, or:

17:08:37 - 17:06:10 = 00:02:27

The object matching the Toppings prep station prepStationGuid value includes:

ticketFiredAt with the value 2026-02-24T17:06:10Z
itemFulfilledAt with the value 2026-02-24T17:10:00Z

This means that on February 24, 2026, the ticket was fired at 05:06:10 PM, and the item was fulfilled at the Toppings prep station KDS device at 05:10:00 PM. The item fulfillment time at the Toppings prep station is three minutes and 50 seconds, or:

17:10:00 - 17:06:10 = 00:03:50

If you use start queue, you can use itemStartedAt, which represents when the item was started on the prep station KDS device. This is when a user selects the ticket from the UNSTARTED side of the prep station KDS device screen and it moves to the COOKING side. The itemStartedAt value uses ISO 8601 format.

If you use start queue and want to know how long an item was actively worked on, use the following equation:

itemFulfilledAt - itemStartedAt

Alternatively, if you use start queue and want to know how long an item waited before being actively worked on, use the following equation:

itemStartedAt - ticketFiredAt

For example, after filtering itemFulfillmentLevel by 0, an object includes the following:

ticketFiredAt with the value 2026-02-24T17:06:10Z
itemFulfilledAt with the value 2026-02-24T17:10:00Z
itemStartedAt with the value 2026-02-24T17:07:32Z

This means that on February 24, 2026, the ticket was fired at 05:06:10 PM and the item was fulfilled at 05:10:00 PM. The item was selected on the prep station KDS device at 05:07:32 PM, which started the item using start queue, and moved it from the UNSTARTED side to the COOKING side of the screen.

The prep station fulfillment time, or time between when the ticket was fired and when the item was fulfilled, is three minutes and 50 seconds, or:

17:10:00 - 17:06:10 = 00:03:50

The time between when the ticket was fired and when the item was started is one minute and 22 seconds, or:

17:07:32 - 17:06:10 = 00:01:22

The time between when the item was started and when the item was fulfilled is two minutes and 28 seconds, or:

17:10:00 - 17:07:32 = 00:02:28

Using the prep station fulfillment time, you can determine which prep stations are taking the longest to prepare items, how fulfillment times at specific prep stations change over time, and compare fulfillment times between different prep stations.

Expediter fulfillment times

The expediter fulfillment time is calculated using the time the item was sent to the kitchen and the time the item was fulfilled at an expediter fulfillment level. The fulfillment level is determined by the itemFulfillmentLevel. If you use a single expediter level, this value is 1. If you use two expediter levels, the value is 2. The Two-level fulfillment setting determines whether you use two expediter levels. Filter itemFulfillmentLevel by 1 or 2, depending on whether you use two expediter levels and which expediter level data you want to look at.

For each object, find ticketFiredAt and itemFulfilledAt. ticketFiredAt represents when the item was sent to the kitchen and itemFulfilledAt represents when the item was fulfilled at the expediter station. Both values use ISO 8601 format.

Using these values and the values for the most recent fulfillment times at the prep station fulfillment level, you can calculate the time between when an item was fulfilled at the prep station and fulfilled at the expediter. Depending on whether you want to find data related to the first-level or second-level expediter, the itemFulfillmentLevel changes.

To collect data used to calculate expediter fulfillment times

Filter itemFulfillmentLevel by 0, and retrieve ticketFiredAt and itemFulfilledAt.
Filter itemFulfillmentLevel by 1, and retrieve ticketFiredAt and itemFulfilledAt.
Optionally, if Two-level fulfillment is set to Two levels, filter itemFulfillmentLevel by 2, and retrieve ticketFiredAt and itemFulfilledAt.
Use the selectionGuid to identify values belonging to the same item.

Once you have these values, you can use them to calculate the following:

The time between when an item was fulfilled at the prep station and fulfilled at the first-level expediter. Use the following equation:
```
itemFulfilledAt (itemFulfillmentLevel: 1) - itemFulfilledAt (most recent itemFulfillmentLevel: 0)
```
This calculation uses the itemFulfilledAt value when itemFulfillmentLevel is filtered by 1, and the most recent itemFulfilledAt value when the itemFulfillmentLevel is filtered by 0, for the same selectionGuid.
The time between when an item was fulfilled at the first-level expediter and fulfilled at the second-level expediter. Use the following equation:
```
itemFulfilledAt (itemFulfillmentLevel: 2) - itemFulfilledAt (itemFulfillmentLevel: 1)
```
This calculation uses the itemFulfilledAt value when itemFulfillmentLevel is filtered by 2, and the itemFulfilledAt value when the itemFulfillmentLevel is filtered by 1, for the same selectionGuid.
The time between when an item was fulfilled at the prep station and fulfilled at the second-level expediter. Use the following equation:
```
itemFulfilledAt (itemFulfillmentLevel: 2) - itemFulfilledAt (most recent itemFulfillmentLevel: 0)
```
This calculation uses the itemFulfilledAt value when itemFulfillmentLevel is filtered by 2, and the most recent itemFulfilledAt value when the itemFulfillmentLevel is filtered by 0, for the same selectionGuid.

For example, you have a location with Two-level fulfillment set to Two levels and are looking at the data for an item sent to a single prep station for a specific order. You filter by the selectionGuid to find the item, and identify the itemFulfilledAt values by the object's itemFulfillmentLevel value:

When the itemFulfillmentLevel is 0, the itemFulfilledAt is 2026-02-24T17:08:37Z.
When the itemFulfillmentLevel is 1, the itemFulfilledAt is 2026-02-24T17:10:12Z.
When the itemFulfillmentLevel is 2, the itemFulfilledAt is 2026-02-24T17:10:44Z.

This means that on February 24, 2026, an item was:

Fulfilled at the prep station at 05:08:37 PM.
Fulfilled at the first-level expediter at 05:10:12 PM.
Fulfilled at the second-level expediter at 05:10:44 PM.

Using this information, you can calculate that:

The time the item spent at the first-level expediter was one minute and 35 seconds, or:
```
17:10:12 - 17:08:37 = 00:01:35 
```
The time the item spent at the second-level expediter was 32 seconds, or:
```
17:10:44 - 17:10:12 = 00:00:32 
```
The time the item spent at both expediters was two minutes and seven seconds, or:
```
17:10:44 - 17:08:37 = 00:02:07 
```

Using the expediter fulfillment time, you can determine how long an item is at an expediter station.