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.

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 Using webhooks and webhooks 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.

  • 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"
  }
}

Restaurant availability testing process

Initial setup and testing

You should have access to an Android tablet or emulator and the most recent Toast APK version in Sandbox. Set up your tablet or emulator as an auto-firing device. For more information, see Setting Up an Auto-fire Device. Submit a test API order using the Toast orders API to ensure the auto-fire device is configured correctly.

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

To trigger an OFFLINE webhook event

  1. While your Toast POS device is online, and with a configured auto-fire device, submit a test order using the Toast API.

  2. Disable the auto-fire device that you previously configured.

  3. Submit another test order and wait at least one minute. One minute is the time needed for the Toast internal job to execute.

  4. After one minute, you will receive an OFFLINE webhook event.

To trigger an ONLINE webhook event

  1. While your Toast POS device is offline, and with a configured auto-fire device that's disabled, enable your auto-fire device.

  2. Submit new test orders using the Toast API and wait at least one minute. One minute is the time needed for the Toast internal job to execute.

  3. After five minutes, you will receive an ONLINE webhook event.

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 enable or disable a third-party online ordering channel in Toast Web. The default setting for an online ordering channel is ONLINE. For more information on third-party online ordering channel toggles, see Third-party online ordering channel toggles.

  • 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

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

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 enabled 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 disabled 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"
  }
}