Empowering Restaurants through Integration

  1. Grubhub Developers
  2. Grubhub Partner Integration V2
  3. API Specification

Tests

The test module allows for creating test orders to validate different components of an integration.

Paths

Create Transmission Test

POST /pos/v1/merchant/{merchant_id}/test/transmission
Description

A transmission test order is a simple order that flows through the entire Grubhub order processing system. This is typically the last step in a go-live process for a new restaurant.

These orders will contain a the lowest-priced menu item not requiring modifiers found on the menu for the given merchant. All line items in this order will be sent with zero cost, so that no actual charges will accrue.

Test orders only exist within the POS ecosystem; they will not show up in the Grubhub for Restaurants app or on any accounting sheet.

Path Parameters
merchant_id
labelRequired
String
The short Grubhub ID for the restaurant.
Body
body
label_outlineOptional
TransmissionTestRequest
Specifies whether the transmission test should be for delivery and/or catering. Note - catering not currently supported.
Responses
200
UUID
Successfully created the transmission test order. Returns the UUID of the resulting order.

Create Menu Test

POST /pos/v1/merchant/{merchant_id}/test/menu
Description

A menu test order enables testing of menu mapping and insertion of a variety of items to the POS. This is typically used for validating a new brand's menu mapping in a lab environment, or performing a comprehensive pre-live validation in the restaurant.

Unlike transmission tests, there is no need to confirm menu test orders, although doing so will have no negative impact.

Path Parameters
merchant_id
labelRequired
String
The short Grubhub ID for the restaurant.
Body
body
label_outlineOptional
MenuTestRequest
Specifies delivery/pickup, catering, and specific line items for an order.
Responses
200
See description
OK - This returns the order object that contains every item on the menu.

Create test delivery

POST /merchant/{merchant_id}/test/delivery
Description

Generates a test delivery event in order to make sure that your delivery status webhook functions properly. The delivery will contain information from the referenced order but will not affect that order or create real-life delivery events.

To configure a delivery webhook for your POS integration, contact your Grubhub account representative.

Path Parameters
merchant_id
labelRequired
String
The short Grubhub ID for the restaurant.
Body
order_id
label_outlineOptional
UUID
The UUID of the order for which you want to create a test delivery event. This must be a real order, as the test will pull diner and order information from that order.
status
label_outlineOptional
DeliveryStatus
Responses
200
N/A
Successfully created the delivery test event.

Creates order with JIT flag triggered

POST /merchant/{merchant_id}/test/jitevent
Description

Generates a test order event in order to make sure that your functionality that triggers JIT event functions properly. The order will contain information from the referenced order but will not affect that order or create real-life delivery events.

To configure a JIT event webhook for your POS integration, contact your Grubhub account representative.

Path Parameters
merchant_id
labelRequired
String
The short Grubhub ID for the restaurant.
Body
order_id
label_outlineOptional
UUID
The UUID of the order for which you want to create a test JIT order event. This can be a a real or fake order ID. If it's a real order, then it will pull use that order data to transmit the JIT event. Otherwise dummy data will be used.
order_number
label_outlineOptional
long
order_status
label_outlineOptional
Status
A status update reflects each successive change in the status of an order.
Responses
200
N/A
Successfully created the JIT test event.

Models

Delivery Status

Status of the delivery. Most of these statuses will only return for Grubhub-managed deliveries. This will return one of the following strings:

  • ANTICIPATED - This order has been set to be fulfilled at a future time, so it has not begun preparation.
  • ESTIMATED - This order has not yet been checked out by the diner, so it has not even been paid for. The numbers given are an estimate provided so that the diner can make a decision with complete information.
  • COMMITTED - The restaurant has accepted the order and is starting to prepare the food.
  • ASSIGNED - A trip offer has been sent to prospective couriers. Once a courier accepts the offer, they will arrive at the restaurant close to the promised fulfillment time to pick up the food.
  • PICKUP_READY - The restaurant has completed preparing the food, so the driver should be there soon to pick it up and deliver it to the diner.
  • IN_TRANSIT - The driver has picked up the food and is on their way to deliver it to the diner.
  • DELIVERED - The driver has handed the food off to the diner and thus completed the delivery.
  • CANCELED - The delivery order has been canceled and will not be taken to the diner. This delivery can be considered finished.
Type

string

Possible Values
  • ESTIMATED
  • COMMITTED
  • ASSIGNED
  • IN_TRANSIT
  • DELIVERED
  • CANCELED
  • PICKUP_READY
  • REJECTED
  • ANTICIPATED

Line

A line item for the order

Properties
description
label_outlineOptional
string
A description of the line item
name
label_outlineOptional
string
The name of the line item
special_instructions
label_outlineOptional
string
Free form text special instructions added by the diner
line_options
label_outlineOptional
List<LineOption>
The options selected
price
label_outlineOptional
integer
The price of this item in US cents. In test transmissions, this will always be 0.
quantity
label_outlineOptional
integer
The number of this item to include
id
label_outlineOptional
string
The Grubhub ID for this line item, may be null
menu_item_id
label_outlineOptional
string
The Grubhub menu item ID (legacy_id)
diner_total
label_outlineOptional
integer
The total cost of this item (and options) in US cents. Because all line items will be 0, this will also be 0.
total
label_outlineOptional
integer
The total cost of this item (and options) in US Cents. Again, this will be 0.
item_type
label_outlineOptional
string
A categorization of this item.
variation_id
label_outlineOptional
string
A Grubhub ID for a specific variation of this line item.
tags
label_outlineOptional
List<integer>
Grubhub tag IDs that apply to this line. item
external_id
label_outlineOptional
string
The external ID that was stored in Grubhub for this menu item ID.

Line Group

A group of line items. Currently, the entire order is within one line group; as group ordering features are rolled out, orders will include multiple line groups.

Properties
label
label_outlineOptional
string
A label for the group of line items. This will be used in the future for the name of a diner on a group order.
lines
labelRequired
List<Line>
The lines items for this portion of the order.

Line Sub Option

Sub options applied to an option. Not currently supported.

Properties
id
label_outlineOptional
string
The Grubhub ID of the sub option.
name
label_outlineOptional
string
The name of the sub option.
price
label_outlineOptional
integer
The price of this sub option in US cents.
choice_category_id
label_outlineOptional
string
The Grubhub category ID.

LineOption

Options applied to a line item.

Properties
label
label_outlineOptional
string
A label for this line item option.
price
labelRequired
integer
The price of this line option in US cents. This should be zero for test transmissions.
id
label_outlineOptional
string
A Grubhub ID (legacy_id) for this option.
name
label_outlineOptional
string
The name of this option.
line_sub_options
label_outlineOptional
List<LineSubOption>
Sub-options applied to this option. Not currently supported.
external_id
label_outlineOptional
string
The external ID that was stored in Grubhub for this option.

Menu Test Request

Request for a menu test.

Properties
is_delivery
label_outlineOptional
boolean
Whether or not the resulting test order(s) should be for delivery (as opposed to pickup). Default is false.
is_catering
label_outlineOptional
boolean
Whether the test order should be for catering. Default is false.
line_groups
label_outlineOptional
List<LineGroup>
Line groups to include on the resulting order(s). If omitted, one of each item on the menu will be ordered. Will include line options, where they are required, but will not select each permutation of an item and options.

Status

The status of an order as it passes through the Grubhub fulfillment flow.

  • ANTICIPATED denotes a future order, which may be cancelled by diner.
  • RESTAURANT_CONFIRMABLE is pending confirmation of receipt by the restaurant. These are effectively new ASAP orders. ANTICIPATED orders will automatically become RESTAURANT_CONFIRMABLE at the promise time, less the restaurant's configured pickup or delivery prep time.
  • DINER_CONFIRMABLE is a status held for future use.
  • CONFIRMED denotes that the order was received by restaurant, even if the restaurant is unable to fulfill it.
  • REJECTED is an error status. For example, if an order is unable to be inserted to the POS, due to menu item mismatch, restaurant offline, etc., the status should be updated to REJECTED. This is not to be used when the order was successfully transmitted, but the restaurant is unable to fulfill it for operational reasons. In that scenario, a Change Request should be submitted to cancel the order.
  • CANCELLED means that a cancellation request by the diner or restaurant has been processed by Grubhub Customer Care.
  • PICKUP_READY indicates that the food is prepared and ready for pickup by the diner or a Grubhub delivery courier.
  • OUT_FOR_DELIVERY means the food is on the way to the diner.
  • FULFILLED denotes that the food has been delivered to or picked up by the diner.
  • UNKNOWN is provided for error handling of strings unmappable to known enumeration values.

Deprecated statuses will be provided when including a legacyStatus query parameter set to TRUE when polling orders. Similarly, legacy statuses will be translated when passed into the order status update endpoint. Confirmation of legacy status translation should be tested with individual integrations.

Type

string

Possible Values
  • ANTICIPATED
  • RESTAURANT_CONFIRMABLE
  • DINER_CONFIRMABLE
  • CONFIRMED
  • REJECTED
  • CANCELLED
  • PICKUP_READY
  • OUT_FOR_DELIVERY
  • FULFILLED
  • UNKNOWN

Transmission Test Request

Request body for creating a transmission test.

Properties
is_delivery
label_outlineOptional
boolean
Whether the test order should be for delivery (as opposed to pickup). Default is false. Note that regardless of this property, for Grubhub Managed Delivery restaurants, there will be no Delivery object created.
is_catering
label_outlineOptional
boolean
Whether the test order should be for catering. Default is false.