Future Orders
While most diners will want their order fulfilled right away, some may want to plan ahead and schedule a future order. These orders will not be sent to the restaurant until the restaurant needs to start preparing the food, though the diner will be charged for their order.
Future orders follow the standard checkout flow with a few exceptions. That's because the Grubhub needs to know when the diner wants their food to be ready for pickup or delivered to their address and if the restaurant will be able to complete that order on the requested time.
Here's the two places where you'll need to send this data:
- During restaurant availability checks.
- When creating a cart.
Availability
An order placed for future fulfillment presents additional complications. You need to know if the restaurant plans to be open and taking orders when the order needs to start being prepared and whether it is open and still delivering when the order is to be fulfilled.
Because the order time corresponds to when the diner would like to receive their food, we build in the time they take to prepare the food and possibly to deliver the food. Depending on the time, we also include rush hour adjustments. So the opening availability has to work backwards from the fulfill time to determine when the restaurant needs to start the order. In cases where it is not open, we can adjust the fulfillment time to reflect the operating hours.
Meanwhile, the fulfillment time needs to consider the closing time of the restaurant, plus the delivery cutoff times.
NOTE: The availability presented for future orders reflects the best information about the restaurant at the time. This information could change between when the order is placed and when it is to be fulfilled.
To check a future order's availability, call GET restaurants/availability_summaries with the query parameters time=[Future Time] and isFutureOrder=true. For example:
GET /restaurants/availability_summaries?ids=11402556&isFutureOrder=true&time=1520613309000 HTTP/1.1
Host: api.grubhub.com
Authorization: Bearer xxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxx
Cache-Control: no-cache
This call produces the following response:
{
"availability_summaries": [
{
"restaurant_id": "11402556",
"premium": true,
"open": true,
"open_delivery": true,
"open_pickup": true,
"available_for_delivery": true,
"available_for_pickup": true,
"delivery_offered_to_diner_location": false,
"restaurant_name": "Design Kitchen Too",
"address": {
"locality": "Holland",
"region": "MI",
"postal_code": "49423",
"street_address": "10 E 10th St",
"country": "USA"
},
"decimal_distance_in_miles": null,
"logo": "https://dtyxqspugqu5z.cloudfront.net/logo/2556/11402556/20170301BackgroudTileopt1.png",
"restaurant_cdn_image_url": null,
"media_image": null,
"future_order_info": {
"order_send_time_delivery": "2018-03-09T15:52:09.000Z",
"open_order_send_time_delivery": true,
"order_send_time_pickup": "2018-03-09T16:00:09.000Z",
"open_order_send_time_pickup": true
},
"next_open_closed_info": {
"next_cutoff_order_send_time_delivery": "2018-03-11T09:45:00.000Z",
"next_cutoff_order_send_time_pickup": "2018-03-11T09:30:00.000Z"
},
"catering_info": {
"catering_sibling_id": null,
"order_thresholds": {
"currency": "USD",
"order_price_bucket_list": [
{
"amount": 250,
"buffer_minutes": 30
}
]
},
"catering": false
},
"cuisines": [],
"price_rating": null,
"delivery_estimate": 30,
"pickup_estimate": 30,
"order_minimum": {
"amount": 1378,
"currency": "USD"
},
"delivery_fee": {
"amount": 0,
"currency": "USD"
},
"delivery_fee_without_discounts": {
"amount": 0,
"currency": "USD"
},
"rating": {},
"delivery_cutoff": 15,
"pickup_cutoff": 30,
"additional_media_images": {},
"available_hours": null,
"available_hours_pickup": null,
"future_order_available_hours_delivery": null,
"future_order_available_hours_pickup": null,
"allowable_order_types": null,
"cutoff_for_delivery": false,
"cutoff_for_pickup": false,
"blacked_out": false,
"white_in": false
}
]
}
When we add the isFutureOrder=true parameter to this request, the response will include a future_order_info object. Here's that object from the response above:
"future_order_info": {
"order_send_time_delivery": "2018-03-09T15:52:09.000Z",
"open_order_send_time_delivery": true,
"order_send_time_pickup": "2018-03-09T16:00:09.000Z",
"open_order_send_time_pickup": true
},
This object contains information about when the restaurant would need to receive the order as to either deliver or provide it as pickup, as well as if the restaurant is open at that time. When determining if a restaurant is available for future orders, these boolean values are the ultimate arbiters. Note that all times are in UTC and should be adjusted to match the restaurant local time.
You can pass time and isFutureOrder as query variables in GET /restaurants/{restaurant_id} to both check menu availability at the future order time and retrieve future_order_info information.
You can pass time as a query variable to GET /restaurants/{restaurant_id}/menu_items/{menu_item_id} to check whether a specific menu item is available at the time of the future order.
Creating a cart
If a restaurant is available for a future order, the next place in the order flow where you will have to deviate from the norm comes when you create the empty cart. In the request body, you will need to include the field, when_for. For example:
POST /carts HTTP/1.1
Host: api-pp.grubhub.com
Authorization: Bearer xxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxx
Content-Type: application/json
Cache-Control: no-cache
{
"when_for": "2018-03-09T11:35:09.000Z"
}
The response here looks like any other cart creation payload. However, a GET call on this cart will include this when_for value, as well as "asap": false.
If you have previously created a cart as ASAP that you want to change to be a future order, call POST /carts/{cart_id} with a when_for value in the body, similar to what is shown in the example above. This will mark the cart as a future order, attach the when_for value, and set asap to false.