A complete order example

In creating an integration with a POS system, it can be helpful to understand the full order flow for a Grubhub diner. We've discussed what you'll need to implement to manage incoming orders and interact with Grubhub's delivery drivers. But in this article, we'll discuss this process from the user perspective, as well as mark the points in which the POS API can affect or is affected by this flow.

A diner's first step is to find a restaurant, whether that's through the search, suggestion carousels on the front page, or previous orders. That information can come directly from the POS system. Grubhub menus should be created directly from the POS system as to link orders processed online with the POS system.

Once they select a restaurant, they start adding menu items to their cart. Before they can checkout, they need to attach a few pieces of information to their cart:

• One or more menu items.
• Delivery or pickup information.
• A payment method.

With these attached to the cart, the diner can check out. Once a cart gets checked out, that's when the order will first hit a linked POS system, either through polling GET /pos/v1/merchant/503736/orders?status=RESTAURANT_CONFIRMABLE or receiving order information through the webhook. If configured correctly, these should show up in the POS system.

The restaurant is then expected to either confirm or reject this order. Call PUT /merchant/{merchant_id}/orders/{order_uuid}/status with a status of either CONFIRMED or REJECTED. For example:

PUT /pos/v1/merchant/503736/orders/d7cydHnLSX-A_tddhMLMGQ/status HTTP/1.1
Host: api-third-party-gtm.grubhub.com
Content-Type: application/json
Authorization: MAC id="sv:v1:xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",nonce="xxxxxxxx:xxxxxxx",bodyhash="xxxxxxxxxxxxxxx=",mac="xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
X-GH-PARTNER-KEY: XXXXXXXXXXXXXXX
{
  "status": "CONFIRMED",
  "wait_time_in_minutes": 20
}

Throughout the order life, a restaurant may want to pass other statuses to Grubhub using this endpoint:

• PICKUP_READY - Indicates that food is ready to be picked up, either by a diner or delivery driver.
• OUT_FOR_DELIVERY - Indicates to the diner that their food is on the way. Most helpful for restaurants that manage their own deliveries.
• FULFILLED - Indicates that a pickup order has been retrieved by a diner or a delivery has been taken to the diner location. Can be helpful in cases where pickup or delivery details are in doubt.

At this point, the restaurant should start preparing the diner's order. If this order is a Grubhub managed delivery order, then it will also be assigned a driver, who will be scheduled to pick up the order when it's ready, which is based on preparation information provided by the restaurant. A restaurant can monitor the delivery information through either polling GET /merchant/{merchant_id}/orders/{order_uuid}/delivery or throught the webhook.

For most order, all that's left is to get the food into the diner's hands, and that responsibility falls on the restaurant, diner, and driver. But not all orders go perfectly - if something goes wrong, Grubhub care will set the order to CANCELLED and will work to resolve the issue to all parties' satisfaction.