Empowering Restaurants through Integration

  1. Grubhub Developers
  2. Delivery Information
  3. API Specification
Follow

Deliveries

The Delivery API lets you track the location of a courier.

Paths

Get Delivery by Delivery ID

GET /deliveries/{delivery_id}
Description

Retrieve a delivery. Will include current status, driver assignment and location (if driver has been assigned).

Path Parameters
delivery_id
labelRequired
UUID
The ID of the delivery to retrieve.
Responses
200
Delivery
OK
404
UNKNOWN
Not Found. May indicate the delivery estimate has expired or the ID is incorrect.

Models

Address

A physical address.

Properties
street_address_1
labelRequired
string
Street address line 1.
street_address_2
label_outlineOptional
string
Street address line 2.
city
labelRequired
string
City or city analogue.
state
labelRequired
string
State, province, or any variant thereof. 2-digit ISO code for US states
postal_code
labelRequired
string
ISO standard postal code, varies per country.
country
label_outlineOptional
string
ISO standard country code. Default to USA.

Courier

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

Properties
id
labelRequired
UUID
A unique ID that Grubhub has assigned to the courier.
name
labelRequired
string
The first name and last initial of the courier.
vehicle
labelRequired
Vehicle
The method of transportation that the courier is using, including a description.
phone
labelRequired
string
A phone number that may be used to contact the courier. Do not distribute to diners. Do not print on receipts.
photoUrl
label_outlineOptional
string
URL to retrieve a photo of the courier for display to the restaurant.
geo
labelRequired
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
id
labelRequired
UUID
A unique Grubhub ID for the delivery.
account_id
labelRequired
UUID
The business account ID that was used to create the delivery.
confirmation_code
label_outlineOptional
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.
trip_id
label_outlineOptional
UUID
The unique Grubhub ID for the trip containing this delivery. Deliveries may be batched together into a single trip. A trip is offered to and accepted by a courier.
name
labelRequired
string
Short text description for the delivery (typically, the name of the diner or delivery recipient).
pickup
labelRequired
Location
The location where the contents of the delivery will be picked up.
dropoff
labelRequired
Location
The location where the contents of the delivery will be dropped off.
flags
label_outlineOptional
List<DeliveryFlag>
A set of flags describing certain attributes of the delivery that may impact dispatch handling.
contents
labelRequired
List<DeliveryItem>
A list of items that are being delivered.
status
labelRequired
DeliveryStatus
The current status of the delivery.
courier
label_outlineOptional
Courier
The courier (driver, biker, etc.) that is currently assigned to the delivery. May change over time.
created
labelRequired
DateTime
Date and time the delivery was created.
pickup_ready
label_outlineOptional
DateTime
When the order was marked as ready to be picked up. Will be absent if null.
times
labelRequired
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
label_outlineOptional
DeliveryTimes
Pickup and dropoff times as they were at the time the delivery was committed.
cost
labelRequired
MoneyAmount
The total cost of the delivery charged by Grubhub.
collected_tip
labelRequired
MoneyAmount
Tip collected by the delivery client to be paid out to the Grubhub driver.
total
label_outlineOptional
MoneyAmount
Total price of the order to the diner.
preferences
label_outlineOptional
DeliveryPreferences
Set of preferred details about a delivery.
metadata
label_outlineOptional
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
label_outlineOptional
string
Not currently supported through DaaS. Special instructions to the courier for delivery setup. Absent if null.
alternate_name
label_outlineOptional
string
An optional alternate contact name.
alternate_phone
label_outlineOptional
string
An optional alternate contact phone number.

Delivery Error Code

Machine-readable code for a specific type of error. Codes map to the following error names:

  • 6001: pickup_location_invalid
  • 6002: dropoff_location_invalid
  • 6003: pickup_out_of_bounds
  • 6004: dropoff_out_of_bounds
  • 6005: no_courier_available (may indicate a market is closed at the requested delivery time)
  • 6006: preferred_pickup_time
  • 6007: catering_not_allowed
  • 6008: account_not_found
  • 6009: preferred_delivery_time
  • 6010: anticipated_not_allowed
Type

integer

Possible Values
  • 6001
  • 6002
  • 6003
  • 6004
  • 6005
  • 6006
  • 6007
  • 6008
  • 6009
  • 6010

Delivery Flag

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

Type

string

Possible Values
  • ALCOHOL
  • LARGE_ORDER

Delivery HTTP Exception

Error response body.

Properties
error_code
labelRequired
DeliveryErrorCode
Machine-readable code for a specific type of error.
error_name
labelRequired
string
Human-readable error message.

Delivery Item

An item within the contents of a delivery.

Properties
description
labelRequired
string
Description of the item being delivered. Typically, the menu item name.
size
label_outlineOptional
DeliveryItemSize
The size of the item. Not currently utilized.
tags
label_outlineOptional
List<DeliveryFlag>
Specifies attributes of an item, which may affect dispatch handling. Note that any client-supplied values are permissible, but only those in the DeliveryFlag enumeration will result in a delivery-level flag, which actually affects dispatch behavior.
quantity
label_outlineOptional
integer
Quantity of the item. Default is 1.

Delivery Item Size

Size of an item.

Type

string

Possible Values
  • XS
  • S
  • M
  • L
  • XL
  • XXL

Delivery Preferences

A set of preferred details about a delivery.

Properties
pickup_time
label_outlineOptional
DateTime
The desired time for a driver to arrive at the pickup location. This influences dispatching, but is not guaranteed to be respected precisely.
delivery_time
label_outlineOptional
DateTime
The desired time for a driver to arrive at the dropoff location. This influences dispatching, but is not guaranteed to be respected precisely.

Delivery Request

A request for a new delivery estimate.

Properties
name
labelRequired
string
Short text description for the delivery. Typically, the name of the diner or delivery recipient.
pickup
labelRequired
Location
Location where the delivery contents will be picked up.
dropoff
labelRequired
Location
Location where the delivery contents will be dropped off.
contents
labelRequired
List<DeliveryItem>
List of items to be delivered.
collected_tip
labelRequired
MoneyAmount
Tip collected by the delivery client to be paid out to the Grubhub driver.
total
label_outlineOptional
MoneyAmount
The total price of the order to the diner.
preferences
label_outlineOptional
DeliveryPreferences
Set of preferred details about a delivery.
metadata
label_outlineOptional
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.
test
label_outlineOptional
boolean
Whether or not this is a test order.
catering_order
label_outlineOptional
boolean
A flag for internal Grubhub clients only designating a catering order. May expose to partners in the future.
setup_instructions
label_outlineOptional
string
Setup instructions for a catering order. Currently allowed for internal Grubhub systems only.
alternate_name
label_outlineOptional
string
An alternate contact name.
alternate_phone
label_outlineOptional
string
An alternate contact phone number.

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
  • ANTICIPATED

Delivery Time

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

Properties
type
labelRequired
DeliveryTimeType
Whether or not this is an estimated or actual time.
timestamp
labelRequired
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
label_outlineOptional
DeliveryTime
Estimated time that the courier will arrive at the pickup location.
pickup
labelRequired
DeliveryTime
Estimated or actual time the courier will or did leave at the pickup location with the order.
dropoffArrival
label_outlineOptional
DeliveryTime
Estimated time the courier will arrive at the delivery location.
dropoff
labelRequired
DeliveryTime
Estimated or actual time the courier will or did complete the delivery.
geofencePickupArrival
label_outlineOptional
DeliveryTime
Actual time that the courier entered into the pickup location defined by the geolocation coordinates. If this has not occurred, object will return null; no estimates will be provided.
geofenceDropoffArrival
label_outlineOptional
DeliveryTime
Actual time that the courier entered into the delivery location defined by 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
labelRequired
number
Latitude coordinate
lng
labelRequired
number
Longitude coordinate

Location

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

Properties
id
label_outlineOptional
string
A unique identifier that the requesting client can set to help identify where deliveries can be batched.
name
labelRequired
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
labelRequired
Address
The physical address of the location.
phone
labelRequired
string
Telephone number for contacting the location.
notes
label_outlineOptional
string
Special instructions for access to the location. E.g., "Park in the alley" or "Buzz #1234 at the gate"
geo
label_outlineOptional
GeoLocation
Latitude and longitude of this location

Money Amount

An amount of money. Includes an amount and currency type. The amount is an integer value of the indivisible unit of a currency (e.g., cents for UDS).

Properties
amount
labelRequired
integer
Value of the amount in the smallest unit of currency. (E.g., cents for USD).
currency
label_outlineOptional
string
ISO standard currency indicator. Default to USD.

Vehicle

A vehicle used by a courier.

Properties
type
labelRequired
VehicleType
The mode of transportation.
description
label_outlineOptional
string
The make, model, and color of the vehicle, where applicable

Vehicle Type

A mode of transportation.

Type

string

Possible Values
  • car
  • bike