Restaurant availability webhook

The restaurant_availability webhook allows you to receive real-time information about a restaurant's ability to accept online orders. The restaurant_availability webhook sends a message when:

  • The Toast Autofire™ device has stopped approving online orders.

  • A third-party online ordering channel (for example, Uber Eats, DoorDash, or Grubhub) was turned on or off in Toast Web.

Restaurant availability webhook messages follow the standard message data schema. The restaurant_availability webhook has two event categories:

  • restaurant_availability

  • restaurant_availability_toggle

When you receive a webhook event for the restaurant_availability event category, the eventCategory value is set to restaurant_availability and the eventType is set to one of the following:

When you receive a webhook event for the restaurant_availability_toggle event category, the eventCategory value is set to restaurant_availability_toggle and the eventType is set to one of the following:

Note

Multiple webhook messages can be sent from Toast depending on the scenario.

For more information about webhooks, see Webhook basics and Message data schema.

Restaurant availability statuses

A restaurant’s availability status is one of the following:

  • ONLINE: The restaurant’s autofire device is approving orders or the restaurant has enabled an integrated third-party online ordering channel.

  • OFFLINE: The restaurant’s autofire device has stopped approving orders or the restaurant has disabled an integrated third-party online ordering channel. When a restaurant is OFFLINE, you can still place online orders via the orders API. You will receive a 200 response and the restaurant will see the order when they come back ONLINE. Toast support recommends waiting to place orders until the restaurant's status is ONLINE.

Note

Placing orders while the restaurant is offline can cause orders to not fire to the kitchen and may result in the restaurant becoming overwhelmed with missed orders once back online. This can contribute to a poor guest ordering experience.

Autofire device stopped approving online orders

The webhook service checks for updates when:

  • An ONLINE restaurant is OFFLINE. Gone OFFLINE means the restaurant’s orders are pending. No order has been approved and autofired for fulfillment in the last five minutes. This indicates that there may be a network issue or other technical problems at the restaurant. For more information, see Troubleshoot Your Autofire Device.

  • An OFFLINE restaurant is now ONLINE. Coming back ONLINE means the restaurant has approved and autofired at least one order in the last five minutes.

The restaurant_availability webhook sends updates when a restaurant's autofire device has stopped auto-approving orders for five minutes. The restaurant availability service runs every minute to check if at least one order has been abandoned, meaning it has not approved and autofired an order within a five minute period. For example, if your guest placed an order at 9:02 AM, and your restaurant stopped auto-approving orders at 9:02 AM, the service runs at 9:03 AM but does not fire a webhook event because only one minute has passed since the order was created and not approved. When the service runs at 9:07 AM and the order was still not been approved, the webhook event fires. For more information about autofiring orders, see Setting up Order Auto-Firing.

Note

If you do not receive any restaurant_availability webhook events, the restaurant should be considered ONLINE. This assumes you are respecting the restaurant’s available operating hours for both ASAP and scheduled orders placed for future fulfillment.

Restaurants using Toast Online Ordering with Manual Approval or Approval Rules configured do not trigger webhook events with the AVAILABILITY_OFFLINE reasonKey. Only restaurants that choose to “Send orders directly to the kitchen” are included in the ONLINE and OFFLINE webhook alerts for this scenario. Restaurants can configure their approval options in Toast Web. These settings do not apply to online ordering integration partners. Orders sent via the orders API are immediately autofired to the kitchen. For more information, see Orders API limitations.

Note

This limitation does not apply to the scenario when a restaurant turns a third-party online ordering channel on or off.

availability_online

The restaurant is online and can accept orders. Attributes in the availability_online event’s payload include:

Value Description

restaurantGuid

A unique Toast POS identifier for the restaurant.

data type: string

format: uuid

status

ONLINE

data type: string

reasonKey

AVAILABILITY_ONLINE

The machine-readable reason why the restaurant is available to accept online orders.

data type: string

reason

Restaurant is approving online orders

The human-readable reason why the restaurant is available to accept orders.

data type: string

Payload for an availability_online event when a restaurant is online and approving orders

{
  "timestamp": "2021-08-23T16:40:00.063Z",
  "eventCategory": "restaurant_availability",
  "eventType": "availability_online",
  "guid": "bf12cb0a-173a-4e66-bd3c-8121d4a5287f",
  "details": {
    "restaurantGuid": "27d35c6a-7068-49f7-bee0-25e654e1227a",
    "status": "ONLINE",
    "reasonKey": "AVAILABILITY_ONLINE",
    "reason": "Restaurant is approving online orders"
  }
}

availability_offline

The restaurant is offline and should not receive orders. Attributes in the availability_offline event’s payload include:

Value Description

restaurantGuid

A unique Toast POS identifier for the restaurant.

data type: string

format: uuid

status

OFFLINE

data type: string

reasonKey

AVAILABILITY_OFFLINE

The machine-readable reason why the restaurant is unavailable to accept online orders.

data type: string

reason

Restaurant cannot accept online orders

The human-readable reason why the restaurant is unavailable to accept online orders.

data type: string

Payload for an availability_offline event when a restaurant is offline and not approving orders

{
  "timestamp": "2021-08-23T16:40:00.063Z",
  "eventCategory": "restaurant_availability",
  "eventType": "availability_offline",
  "guid": "bf12cb0a-173a-4e66-bd3c-8121d4a5287f",
  "details": {
    "restaurantGuid": "27d35c6a-7068-49f7-bee0-25e654e1227a",
    "status": "OFFLINE",
    "reasonKey": "AVAILABILITY_OFFLINE",
    "reason": "Restaurant cannot accept online orders"
  }
}

Third-party online ordering channel has been manually turned on or off

A third-party online ordering channel is any online ordering partner such as Uber Eats, DoorDash, or Grubhub. Restaurants can turn a third-party online ordering channel on or off in Toast Web. The default setting for an online ordering channel is ONLINE. For more information about turning on or off a third-party online ordering channel, see Third-party online ordering partner toggles.

Note

A webhook message is sent every time an online ordering channel is turned on or off.

  • If a restaurant’s status is ONLINE, this means that the restaurant has manually turned on online ordering for that ordering channel. An ONLINE status means the restaurant is available for guests to place orders.

  • If a restaurant’s status is OFFLINE, this means that the restaurant has manually turned off online ordering for that ordering channel. An OFFLINE status means the restaurant is unavailable for guests to place orders.

Note

If the restaurant has manually turned on ordering from third-party online ordering channels on Toast Web, but the restaurant's availability status is showing still OFFLINE, check if the autofire device is online and operational. For more information, see Troubleshoot Your Autofire Device.

toggle_availability_online

The restaurant has turned on online ordering for that ordering channel. Attributes in the toggle_availability_online event’s payload include:

Value Description

restaurantGuid

A unique Toast POS identifier for the restaurant.

data type: string

format: uuid

status

ONLINE

data type: string

reasonKey

TOGGLE_ENABLED

The machine-readable reason why the restaurant is available to accept online orders.

data type: string

reason

User enabled integration

The human-readable reason why the restaurant is available to accept orders.

data type: string

Payload for a toggle_availability_online event when a restaurant is online and has turned on online ordering

{
  "timestamp": "2021-08-23T16:40:00.063Z",
  "eventCategory": "restaurant_availability_toggle",
  "eventType": "toggle_availability_online",
  "guid": "bf12cb0a-173a-4e66-bd3c-8121d4a5287f",
  "details": {
    "restaurantGuid": "27d35c6a-7068-49f7-bee0-25e654e1227a",
    "status": "ONLINE",
    "reasonKey": "TOGGLE_ENABLED",
    "reason": "User enabled integration"
  }
}

toggle_availability_offline

The restaurant has turned off online ordering for that ordering channel. Attributes in the toggle_availability_offline event’s payload include:

Value Description

restaurantGuid

A unique Toast POS identifier for the restaurant.

data type: string

format: uuid

status

OFFLINE

data type: string

reasonKey

TOGGLE_DISABLED

The machine-readable reason why the restaurant is unavailable to accept online orders.

data type: string

reason

User disabled integration

The human-readable reason why the restaurant is unavailable to accept orders.

data type: string

Payload for a toggle_availability_offline event when a restaurant is offline and has turned off online ordering

{
  "timestamp": "2021-08-23T16:40:00.063Z",
  "eventCategory": "restaurant_availability_toggle",
  "eventType": "toggle_availability_offline",
  "guid": "bf12cb0a-173a-4e66-bd3c-8121d4a5287f",
  "details": {
    "restaurantGuid": "27d35c6a-7068-49f7-bee0-25e654e1227a",
    "status": "OFFLINE",
    "reasonKey": "TOGGLE_DISABLED",
    "reason": "User disabled integration"
  }
}

Testing the restaurant availability webhook

Setup and testing

Before testing, you need an Android tablet or emulator and the most recent Toast APK version in a Sandbox environment. Set up your tablet or emulator as an autofire device. For more information, see Setting Up an Auto-fire Device. Submit a test API order using the Toast orders API to ensure the autofire device is configured correctly.

The following procedures describe how to trigger OFFLINE and ONLINE webhook events.

Note

Restaurants must choose to the “Send orders directly to the kitchen” approval rule to receive the ONLINE and OFFLINE webhook events. For more information, see Get Started With Online Ordering.

To trigger an OFFLINE webhook event

  1. Ensure that your Toast POS device is online and you have configured an autofire device.

  2. Submit a test order using the orders API. For more information, see Orders API overview.

  3. Disable the autofire device. For more information on how to disable your autofire device, see Set up Order Auto-firing.

  4. Submit another test order. After five minutes, you receive an OFFLINE webhook event.

To trigger an ONLINE webhook event

  1. Enable the autofire device.

  2. Submit another test order using the orders API. After one minute, you receive an ONLINE webhook event.