Orders

The orders API lets you retrieve a diner's previous orders, complete with menu items, pickup or delivery information, and payment information. You can use these to build a new cart and reorder previous meals.

Paths

Retreive previous orders

GET /diners/{diner_id}/orders

Description

Returns an array of previous orders.

Path Parameters

diner_id

UUID

The ID of the diner whose orders you want to retreive.

Responses

200

OrderHistoryResponse

Track order status

GET /diners/{diner_id}/orders/{order_id}/order-status

Description

Returns information about current fulfillment estimates as well as the current status of the order.

Path Parameters

diner_id

UUID

The ID of the diner whose order you want to track.

order_id

UUID

The ID of the order you want to track.

Responses

200

OrderEventList

Example

{
    "estimate_start_time": "2018-07-27T16:25:00.000Z",
    "estimate_end_time": "2018-07-27T16:35:00.000Z",
    "expected_delivery_time": "2018-07-27T16:29:41.500Z",
    "order_id": "633257d0-91b2-11e8-bb45-9f39ece5451d",
    "order_events": [
        {
            "type": "UNCONFIRMED",
            "event_time": "2018-07-27T15:39:18.257Z"
        },
        {
            "type": "UNCONFIRMED",
            "event_time": "2018-07-27T15:39:19.184Z"
        }
    ]
}

Models

CartLine

Details about a single menu item line in a cart.

Properties

UUID

The ID for this line within a cart.

menu_item_id

String

The ID of the menu item added to this line item.

name

String

The name of the menu item on this line.

price

Integer

The price the diner is paying for this menu item in cents.

display_price

Integer

The price displayed for this menu item.

quantity

int

The total number of this menu item included in this cart.

diner_total

Integer

The total cost to the diner from this cart line.

options

CartLineOption

A list of options that the diner selected for this menu item.

CartLineOption

The options that the diner selected for a menu item.

Properties

String

The ID associated with this option.

name

String

The display name of the option.

price

Integer

The increase in price due to this option, in cents.

DeliveryInfo

Information on how to deliver this order to the diner.

Properties

street_address1

String

The primary street address.

cross_streets

String

The nearest cross street to the street address.

street_address2

String

Additional address information, such as apartment number.

address_locality

String

The city, town, or other locality in which this address is located.

address_region

String

The state or other region in which this address is located.

postal_code

String

The ZIP Code or Postcode of the address.

delivery_instructions

String

Any delivery instructions provided by the diner.

name

String

The diner name. Used to verify the order upon delivery.

phone

String

The contact phone number for the diner.

String

The contact email address for the diner.

address_country

String

The country in which this address is located.

green_indicated

boolean

Whether the diner has indicated that they want the restaurant to not include plastic silverware in order to save the environment.

latitude

String

The latitude of the address.

longitude

String

The longitude of the address.

DinerInfo

Information about a diner associated with an order or cart.

Properties

UUID

The ID of the diner.

name

String

The full name of the diner.

String

The email address that will be used to log the diner in and communicate order status changes.

phone

String

The diner's phone number, which restaurants and drivers will receive in order to coordinate delivery and communicate any issues.

FulfillmentEstimate

The estimated minimum and maximum time for fullfilment according to the selected fullfillment method.

Properties

time

DateTime

The lower bound time that the order is estimated to be fullfilled.

maxTime

DateTime

The upper bound time that the order is estimated to be fullfilled.

FulfillmentInfo

Information about how to delivery or handle pickup for the current order.

Properties

type

String

The type of order fulfillment associate with this order. Either "DELIVERY" or "PICKUP".

delivery_info

DeliveryInfo

The information needed to deliver this order to the diner.

pickup_info

PickupInfo

Information needed to arrange pickup with the diner.

incomplete_delivery

IncompleteDelivery

Incomplete delivery information that will still allow the driver to reach the diner.

incomplete_pickup

IncompletePickup

An empty object used to indicate that the cart is for a pickup order without providing pickup information about the diner.

IncompleteDelivery

Incomplete delivery information that will still allow the driver to reach the diner.

Properties

latitude

String

The latitude coordinate of the delivery address.

longitude

String

The longitude coordinate of the delivery address.

Order

Information about a previously placed order.

Properties

UUID

The ID of the order.

time_placed

DateTime

The date and time when this order was placed.

start_time

DateTime

The date and timed on which the diner began this order.

is_asap

boolean

Whether this order was requested to bbe fulfilled as soon as possible.

currency

String

The currency in which the prices and other costs are valued in.

diner_info

DinerInfo

Information about the diner who placed this order.

fulfillment_info

FulfillmentInfo

Information about how the restaurant will fulfill the diner's order.

order_number

Integer

A number given to identify the order to the restaurant. This differs from the order ID, which is a unique UUID in the Grubhub system.

state

String

The current state of this order within the fulfillment pipeline.

order_tracking

OrderTracking

Order tracking information for this order.

payments

Paymemts

The payment methods applied to this order and the total order cost that those methods cover.

charges

OrderCharges

Details about the costs associated with this order.

restaurant

List<Restaurant>

Information about the restaurants from which the diner ordered food.

when_for

DateTime

The date and time which this order was expected to be ready.

fulfillment_estimate

FulfillmentEstimate

Estimates on the earliest and latest that this order was to be fulfilled.

system_of_record

String

The primary ordering system in which this order is tracked.

OrderCharges

The charges associated with an existing order.

Properties

diner_subtotal

Integer

The total of all menu items added to this cart before fees and taxes.

fees

OrderFees

Information about the fees applied to this order.

taxes

OrderTaxes

Information about the taxes applied to this order.

tip

Tip

Information about the tip applied to this order.

diner_grand_total

Integer

The total amount of the bill for this order, including menu items, taxes, fees, and tip.

lines

OrderLines

A break down of each menu item line.

OrderEvent

A time-stamped status change event associated with an order.

Properties

type

Status

The status change associated with this event.

event_time

DateTime

The time that this status change occurred.

OrderEventList

Estimated time that an order will be fulfilled, as well as time-stamped events related to that order.

Properties

estimate_start_time

DateTime

The beginning of the estimated fulfillment time range. This value is not a guarantee, and the actual fulfillment could fall outside of this range.

estimate_end_time

DateTime

The end of the estimated fulfillment time range. This value is not a guarantee, and the actual fulfillment could fall outside of this range.

expected_delivery_time

DateTime

The time within this range we estimate that the order will be fulfilled.

order_events

List<OrderEvent>

An array of status changes and the times at which they occurred.

OrderFees

Information about the delivery and other fees that apply to an order.

Properties

total

Integer

The total amount of fees to add to an order, in cents.

delivery

Integer

The fee for delivery.

OrderHistoryResponse

Full details about an order as returned from an orders request.

Properties

orders

List<Order>

Information about a single order.

OrderLines

A break down of each menu item line within a completed order.

Properties

line_items

CartLine

Information about an individual menu item line within this cart.

OrderPayments

The payments applied to this order and the total amount that they covered.

Properties

total

Integer

The total amount covered by the payments in the `payments` array.

payments

List<Payment>

Information about a payment applied to this order.

OrderTaxes

Information about the taxes applied to an order.

Properties

total

Integer

The total taxes appied to an order in cents.

sales

Integer

The amount of sales taxes applied to a cart in cents.

delivery

Integer

The taxes related to delivery applied to a cart.

OrderTracking

Information about whether this order is tracked.

Properties

enabled

boolean

Whether this order is able to be tracked.

Payment

Information about a single payment attached to an order.

Properties

String

The ID value that identifies this payment as attached to a specific order.

type

String

The type of payment; one of either "CREDIT_CARD", "PAYPAL_EXPRESS", or "AMEX_EXPRESS".

amount

Integer

The amount of the order bill that this payment covers.

PickupInfo

Information required to arrange pickup with the diner.

Properties

name

String

The name of the diner picking up the order.

phone

String

The phone number of the diner.

String

The email address of the diner.

pickup_instructions

String

Any instructions that the diner has provided to the restaurant for pickup.

green_indicated

boolean

Whether the diner has indicated that they do not want plastic utensils with their food.

Restaurant

Information about a single restaurant.

Properties

String

The unique identifer for this restaurant.

name

String

The display name of the restaurant.

img_url

String

The URL of the image used to represent this restaurant.

Status

The status of an order as it passes through the Grubhub fulfillment flow. The most common statuses are described below.

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
STARTED
UNCONFIRMED
CALLING
FAILED_TRANSMISSION
FAILED_CONFIRMATION
FAILED_ATTENTION
FAILED_INTERVENTION
FAILED
BLOCKED_FRAUD
FAILED_MANAGED_DELIVERY_TRANSMISSION
READY_FOR_PICKUP
READY_FOR_DELIVERY
COMPLETE
MANAGED_FOOD_IS_READY

Tip

Information about the tip applied to an order.

Properties

amount

String

The total amount of the tip in cents.

type

String

How the tip amount was collected. This will be either "INCLUDE_IN_BILL" or "CASH".

Empowering Restaurants through Integration

Orders

Paths

Retreive previous orders

Track order status

Models

CartLine

CartLineOption

DeliveryInfo

DinerInfo

FulfillmentEstimate

FulfillmentInfo

IncompleteDelivery

Order

OrderCharges

OrderEvent

OrderEventList

OrderFees

OrderHistoryResponse

OrderLines

OrderPayments

OrderTaxes

OrderTracking

Payment

PickupInfo

Restaurant

Status

Tip