Interacting with Drivers
NOTE: This article only applies if you use Grubhub managed delivery to fulfill orders. If your merchants will always use another delivery fulfillment provider, then you will not need to implement these features in your POS.
For many orders, the diner expects their food to come to them. That means a driver needs to interact with both the restaurant and the diner. A driver is often the only person that a diner interacts with when they order from Grubhub.
We like to improve all interactions in our ecosystem by setting expectations and provide up-to-date information to diners, driver, and restaurants. To enable that information sharing, your POS integration can be configured to send and receive information about drivers. At a minimum, your POS needs to be able to indicate that an order is ready to pickup, as shown below.
There are two primary methods you'll need to implement in order to manage driver information.
Retrieve Delivery Information
Any time after a delivery order has been created and confirmed, a driver may be assigned. This driver will arrive at the specified restaurant at a time based on the restaurants current estimates, either as merchant defaults or estimates send with an order update (see below).
You'll want to make that delivery information available to POS users, as it includes the following:
- Items to be delivered
- Pickup and dropoff locations
- Driver information
- Committed and estimated times for pickup and delivery.
There are two ways to get delivery information:
- By order ID:
GET /merchant/{merchant_id}/orders/{order_uuid}/delivery - By merchant group ID:
GET /group/{group_key}/deliveries
Both of these endpoints return a Delivery object, which looks like this:
{
"delivery": {
"id": "xxx-xxxxxxxxxxxxxx",
"account_id": "xxxxxxxxxxxxxxxx",
"confirmation_code": "HVUYBJH",
"trip_id": "UvYO6VyVEeiVadmHZVMREg",
"name": "Grubhub order 76884765873",
"pickup": {
"name": "Good Food, Inc.",
"address": {
"street_address1": "123 Main Ave",
"city": "Anytown",
"state": "NY",
"postal_code": "11111",
"country": "USA"
},
"phone": "4045551212",
"notes": "",
"geo": {
"lat": 37.65947723,
"lng": -81.43487549
}
},
"dropoff": {
"name": "Steve McSteverson",
"address": {
"street_address1": "2940 Secondary Ln",
"street_address2": "",
"city": "Anytown",
"state": "NY",
"postal_code": "11111",
"country": "US"
},
"phone": "4045552121",
"notes": "",
"geo": {
"lat": 37.67552947,
"lng": -81.40675355
}
},
"contents": [{
"description": "Slider",
"quantity": 6
}, {
"description": "Chocolate Chip Cookie",
"quantity": 1
}, {
"description": "Chocolate Chip Cookie",
"quantity": 1
}],
"status": "DELIVERED",
"courier": {
"id": "X-xxxxxxxxxxxx",
"name": "Jack Burton",
"vehicle": {
"type": "car",
"description": ""
},
"phone": "4045552323",
"photo_url": "https://s3.amazonaws.com/gh-prod-drivers-data/drivers/xxxxx/avatar.png",
"geo": {
"lat": 37.67577137428678,
"lng": -81.40696178943328
}
},
"created": "2018-05-21T00:42:03.300Z",
"pickup_ready": "2018-05-21T00:32:09.492Z",
"pickup_feasibility_time": "2018-05-21T01:12:39.535Z",
"times": {
"pickup_arrival": {
"type": "actual",
"timestamp": "2018-05-21T02:05:51.993Z"
},
"pickup": {
"type": "actual",
"timestamp": "2018-05-21T02:10:58.458Z"
},
"dropoff_arrival": {
"type": "actual",
"timestamp": "2018-05-21T02:38:10.913Z"
},
"dropoff": {
"type": "actual",
"timestamp": "2018-05-21T02:38:12.020Z"
},
"geofence_pickup_arrival": {
"type": "actual",
"timestamp": "2018-05-21T02:05:52.100Z"
}
},
"committed_times": {
"pickup_arrival": {
"type": "estimate",
"timestamp": "2018-05-21T01:12:39.535Z"
},
"pickup": {
"type": "estimate",
"timestamp": "2018-05-21T01:15:39.535Z"
},
"dropoff_arrival": {
"type": "estimate",
"timestamp": "2018-05-21T01:26:46.535Z"
},
"dropoff": {
"type": "estimate",
"timestamp": "2018-05-21T01:28:46.535Z"
}
},
"cost": {
"amount": 696,
"currency": "USD"
},
"collected_tip": {
"amount": 200,
"currency": "USD"
},
"total": {
"amount": 1822,
"currency": "USD"
},
"preferences": {
"pickup_time": "2018-05-21T01:15:39.535Z",
"delivery_time": "2018-05-21T01:23:41.672Z"
},
"metadata": {
"grubhub_cust_id": "735541",
"grubhub_diner_uuid": "f3e00ff0-5c8a-11e8-ad7c-810ac177323e",
"grubhub_order_uuid": "bbd2cef4-5c89-11e8-9ff1-73136060c4b4",
"grubhub_order_number": "321404324050800",
"grubhub_requested_fulfillment_at": "2018-05-21T01:23:41.672Z",
"grubhub_brand": "GRUBHUB",
"grubhub_contact_email": "grubhub987654321@gmail.com",
"grubhub_future_check_v2": "true",
"grubhub_order_type": "ANTICIPATED",
"grubhub_confirmation_code": "LNQDMB",
"grubhub_has_alcohol": "false",
"grubhub_not_for_biker": "false",
"grubhub_needs_attention": "false",
"grubhub_quote.currency": "USD",
"grubhub_quote.amount": "398",
"grubhub_quote.id": "1e7d67c1-56b2-41f6-91a8-2d51f933de5f",
"grubhub_quote.reasons": "BASE_DELIVERY_RATE, BASE_DISTANCE_RATE",
"grubhub_quote.breakdown": "[{\"id\":\"uo57eAfgR3mF3fVaf9_UPQ\",\"cost\":{\"amount\":300,\"currency\":\"USD\"},\"reason\":\"BASE_DELIVERY_RATE\",\"type\":\"DELIVERY\"},{\"id\":\"uo57eAfgR3mF3fVaf9_UPQ\",\"cost\":{\"amount\":50,\"currency\":\"USD\"},\"reason\":\"BASE_DISTANCE_RATE\",\"type\":\"DISTANCE\"}]"
},
"catering_order": false,
"ticket_id": null,
"update_time": "AUFOYFygEeil4nOupoN1xg"
},
"time_stamp": "2018-05-21T02:38:42.326Z",
"delivery_status": "DELIVERED"
}
As you can see, there's a lot of important information in there that may be useful to whoever is using your POS system. From this, you can:
- Print delivery receipts that include all items and delivery instructions.
- Provide all diner information.
- Identify the driver (
courier) by name and photo. - Know when to expect the driver to show up.
How you build this information into your POS is up to you, but we strongly recommend that, if you plan on using your POS in restaurants that accept delivery orders, you include interfaces to this data.
Notifying Drivers of Order Status
In addition to learning about deliveries and the drivers who will carry them, you want to make sure the drivers know about the order they will pickup. While Grubhub handle a lot of the order details, you will need to provide information about the status of that order.
Status updates use the PUT /merchant/{merchant_id}/orders/{order_uuid}/status. For delivery drivers, there are three important statuses:
CONFIRMED- This creates the delivery object, attempts to assign a driver, and sets the pickup and promised delivery times.PICKUP_READY- Lets the driver know that the order is ready to be picked up and taken to the diner.OUT_FOR_DELIVERY- Lets the diner know that their food is on the way.
Your implementation should have the means to set all three of these statuses.
To make sure that time estimates drivers and diners receive reflects the current situation at the restaurant, you can send order updates that include the field, wait_time_in_minutes. This field overrides the time estimate sent as the pickup promise time and used to create the delivery promise time.