Deliveries

Through the Delivery component of the POS API provides a means to get delivery-specific information for Grubhub Delivery Orders. For example, you can track delivery status, driver assignment, and geolocation.

Polling and webhooks are both available as options to get event updates; however, subscribing to webhooks is preferred for high traffic clients.

Delivery objects include the following time information:

Estimates of the pickup and delivery location arrival times.
Pickup and delivery location departure times.
Time when the driver entered within a geofence of the pickup and delivery locations.

With this information, you can:

Provide customers with their expected delivery time.
As a quick-service restaurants, assemble the customer's food when the driver is nearby.
Use time records to update estimate values.

Paths

Get Delivery by Order ID

GET /pos/v1/merchant/{merchant_id}/orders/{order_uuid}/delivery

Description

Retrieve the current state of a Delivery for an Order.

Path Parameters

merchant_id

string

The Grubhub short ID for the restaurant. Corresponds to a single location.

order_uuid

UUID

The unique ID for the Order whose Delivery information is being requested.

Responses

200

Delivery

Example

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

Get Delivery by Delivery ID

GET /pos/v1/deliveries/{delivery_id}

Description

Deprecated. Provided for backwards compatibility only. Retrieve the current state of a Delivery.

Path Parameters

delivery_id

UUID

The ID of the delivery to retrieve.

Responses

200

Delivery

Example

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

Models

Address

A physical address.

Properties

street_address_1

string

Street address line 1.

street_address_2

string

Street address line 2.

city

string

City or city analogue.

state

string

State, province, or any variant thereof. 2-digit ISO code for US states

postal_code

string

ISO standard postal code, varies per country.

country

string

ISO standard country code. Default to USA.

Courier

A courier (driver, biker, etc.) that has been assigned to fulfill a delivery.

Properties

UUID

A unique ID that Grubhub has assigned to the courier.

name

string

The first name and last initial of the courier.

vehicle

Vehicle

The method of transportation that the courier is using, including a description.

phone

string

A phone number that may be used to contact the courier. Do not distribute to diners. Do not print on receipts.

photoUrl

string

URL to retrieve a photo of the courier for display to the restaurant.

geo

GeoLocation

The current location of the courier. Updated approximately every 60 seconds.

Delivery

A delivery that has been created as the result of a delivery request.

Properties

UUID

A unique Grubhub ID for the delivery.

account_id

UUID

The business account ID that was used to create the delivery.

confirmation_code

string

A Grubhub 6-character code for referencing the delivery by humans. This should be displayed to the end user for reference when calling in to Grubhub customer care. It is also provided to the driver.

name

string

Short text description for the delivery (typically, the name of the diner or delivery recipient).

pickup

Location

The location where the contents of the delivery will be picked up.

dropoff

Location

The location where the contents of the delivery will be dropped off.

flags

List<DeliveryFlag>

A set of flags describing certain attributes of the delivery that may impact dispatch handling.

contents

List<DeliveryItem>

A list of items that are being delivered.

status

DeliveryStatus

The current status of the delivery.

courier

Courier

The courier (driver, biker, etc.) that is currently assigned to the delivery. May change over time.

created

DateTime

Date and time the delivery was created.

pickup_ready

DateTime

When the order was marked as ready to be picked up. Will be absent if null.

times

DeliveryTimes

Pickup and dropoff estimate or actual times. Estimates are updated approximately every 60 seconds. After a pickup or dropoff event has occurred, actual times are returned instead of estimates.

committed_times

DeliveryTimes

Pickup and dropoff times as they were at the time the delivery was committed.

preferences

DeliveryPreferences

Set of preferred details about a delivery.

metadata

object

String map of client-supplied metadata for the delivery. Both internal Grubhub systems and partner systems may provide metadata, so it is advised to implement a namespacing convention for partner-supplied keys.

setup_instructions

string

Not currently supported through DaaS. Special instructions to the courier for delivery setup. Absent if null.

alternate_name

string

An optional alternate contact name.

Delivery Flag

Specifies an attribute of the delivery, which may affect dispatch handling.

Type

string

Possible Values

ALCOHOL
LARGE_ORDER

Delivery Item

An item within the contents of a delivery.

Properties

description

string

Description of the item being delivered. Typically, the menu item name.

size

DeliveryItemSize

The size of the item. Not currently utilized.

Delivery Item Size

Size of an item.

Type

string

Possible Values

Delivery Preferences

A set of preferred details about a delivery.

Properties

pickup_time

DateTime

The desired time for a driver to arrive at the pickup location.

delivery_time

DateTime

The desired time for a driver to arrive at the dropoff location.

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

Delivery Time

Estimated or actual time that a delivery event will or has taken place.

Properties

type

DeliveryTimeType

Whether or not this is an estimated or actual time.

timestamp

DateTime

The time that an event occurred.

Delivery Time Type

Whether a time is estimated or actual.

Type

string

Possible Values

estimate
actual

Delivery Times

Estimated or actual times for pickup and drop off of a delivery.

Properties

pickupArrival

DeliveryTime

Estimated time that the courier will arrive at the pickup location.

pickup

DeliveryTime

Estimated or actual time the courier will or did leave at the pickup location with the order.

dropoffArrival

DeliveryTime

Estimated time the courier will arrive at the delivery location.

dropoff

DeliveryTime

Estimated or actual time the courier will or did complete the delivery.

geofencePickupArrival

DeliveryTime

Actual time that the courier entered within 150 meters of the geolocation coordinates. If this has not occurred, object will return null; no estimates will be provided.

geofenceDropoffArrival

DeliveryTime

Actual time that the courier entered within 150 meters of the geolocation coordinates. If this has not occurred, object will return null; no estimates will be provided.

Geo Location

Latitude and longitude for a location.

Properties

lat

number

Latitude coordinate

lng

number

Longitude coordinate

Location

Geographic and contact details for where delivery contents will be picked up or dropped off.

Properties

string

A unique identifier that the requesting client can set to help identify where deliveries can be batched.

name

string

A short description of the location. Typically, the restaurant name and parenthetical location identifier for pickup locations. E.g., "Brian's Diner (on Clark St.)".

address

Address

The physical address of the location.

phone

string

Telephone number for contacting the location.

notes

string

Special instructions for access to the location. E.g., "Park in the alley" or "Buzz #1234 at the gate"

geo

GeoLocation

Latitude and longitude of this location

Vehicle

A vehicle used by a courier.

Properties

type

String

The mode of transportation. Possible values include car, motorcycle, and bike, though other values are possible.

description

string

The make, model, and color of the vehicle, where applicable

Empowering Restaurants through Integration

Deliveries

Paths

Get Delivery by Order ID

Get Delivery by Delivery ID

Models

Address

Courier

Delivery

Delivery Flag

Delivery Item

Delivery Item Size

Delivery Preferences

Delivery Status

Delivery Time

Delivery Time Type

Delivery Times

Geo Location

Location

Vehicle