Orders

The order management module allows for retrieving and managing orders placed for a given location.

Basic Workflow

Receive Orders

Either by polling for orders by merchant or group or by subscribing to webhook notifications
Identify new orders by filtering for the RESTAURANT_CONFIRMABLE status
Future orders are available by filtering for the ANTICIPATED status
Future orders will automatically transition to RESTAURANT_CONFIRMABLE at the promise time, less the default delivery or pickup fulfillment duration configured for the merchant. For Grubhub Managed Delivery restaurants, the default kitchen prep time configured for the merchant is used for this purpose.

Confirm the Order Inserted to the POS

On successful insertion of an order to the POS, update order status to CONFIRMED, optionally indicating an estimate of when the order will be prepared (for pickup or managed delivery) or delivered (for self-delivery).
If the order failed to insert to the POS, update order status to REJECTED with a reason code.

Handle Change Requests

If the restaurant needs to change an order or cancel an order, you can submit a Change Request on their behalf.

Handle Grubhub Managed Delivery Updates

If Grubhub is providing the delivery driver--as denoted by order.delivery_info.is_managed_delivery == true--you can either poll for delivery updates or subscribe to webhook notifications for delivery updates. These will include driver contact information, driver arrival ETAs, and driver lat/lng.

Update order status when prepared and/or fulfilled

Updating the status of an order as it proceeds through the fulfillment workflow will enable Grubhub to relay notifications to the driver (if managed delivery) and the diner.
Update order status to PICKUP_READY when a pickup order or a managed delivery order is ready to be picked up by the diner or Grubhub driver.
Update order status to OUT_FOR_DELIVERY when self-delivery takes the order out.
Update order status to FULFILLED upon self-delivery completion.

Order Validation

Order Validation Workflow

Order Status for Pre-Checkout Validation that partners can subscribe to through a webhook. Grubhub sends webhook prior to the diner placing orders. Partner should attempt to plug this into the relevant order validation endpoint at the merchant POS to perform real-time check as to whether the incoming order would be a successful one or not. The Partner is expected to respond with a Confirmed or a Rejected status.

Partners can expect to receive several validation requests per order as this is driven by cart alterations performed by customers. If Partner responds back with a rejected status , Grubhub prevents customers from placing the order by displaying an error when attempting to check-out.

Grubhub sends a POS_VALIDATION webhook request.

  {
      "uuid": "AQ2X8qgOEe2X8yWWroS6Vg",
      "merchant_uuid": "B-GlkOqmEemWQeGu2Sk9uQ",
      "order_number": "",
      "is_test": false,
      "status": "POS_VALIDATING",
      "statusHistory":
      [
    {
      "status": "ANTICIPATED",
      "timestamp": "2023-02-09T00:42:23.605Z",
      "update_source": "DINER"
  }

Partner responds with POS_VALIDATED or POS_VALIDATION_REJECTED as a response.

If a POS_VALIDATION_REJECTED is sent to Grubhub, an error message is also required

If the response is POS_VALIDATED, Grubhub will send a RESTAURANT_CONFIRMABLE webhook.

Example of Expected Partner Responses

Rejected Response

  {
    "updated_status": "POS_VALIDATION_REJECTED",
    "reason_code": "RESTAURANT_OFFLINE",y^
    "description": "Restaurant Closed"
  }

Validated Response

  {
    "updated_status": "POS_VALIDATED"
  }

Order Validation Webhook Specification

Paths

Get Orders By Merchant, Status and Date Range

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

Description

Polling endpoint for getting all orders for a merchant in a given state in the given time range.

Maximum time range for polling is 15 minutes.

Path Parameters

merchant_id

string

The short Grubhub ID for the restaurant.

Query Parameters

status

List<Status>(Comma Separated)

Filters returned orders by the provided statuses.

start

dateTime

Start time for the query

end

dateTime

End time for the query. Must be within 24 hours of start time.

legacyStatus

boolean

If true, order statuses returned will be translated to legacy order statuses. Default is FALSE.

Responses

200

List<Order>

Get Orders By Group, Status and Date Range

GET /pos/v1/group/{group_key}/orders

Description

Polling endpoint for getting all orders for a group of merchants in a given state in the given time range.

Path Parameters

group_key

string

The group key

Query Parameters

status

List<Status>(Comma Separated)

Filters returned orders by the provided statuses.

start

dateTime

Start time for the query

end

dateTime

End time for the query

Responses

200

List<Order>

Get Order by UUID

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

Description

Returns the single order requested by its UUID.

Path Parameters

merchant_id

string

The short Grubhub ID for the restaurant.

order_uuid

uuid

The UUID of the order.

Responses

200

Order

404

Error

Order doesn't exist

Update Order Status

PUT /pos/v1/merchant/{merchant_id}/orders/{order_uuid}/status

Description

Update the order status.

Path Parameters

merchant_id

string

The short Grubhub ID for the restaurant.

order_uuid

uuid

The UUID of the order.

Body

body

StatusUpdateRequest

The request payload

Responses

200

Order

404

Error

Order doesn't exist

Order Validation Outgoing Webhook

POST /{partner outgoing webhook url for validation}

Description

Partners may register, via Partner Accounts, webhook callback endpoints to be notified of order validation requests. For security, a Callback url is expected to use HTTPS, enforced at registration time (Partner Accounts). Order Example

Body

PosOrder

Unknown

Order for validation, Status will be "POS_VALIDATING"

Responses

200

ValidateOrderWebhookResponse

Example

{
  "uuid": "1A5tVq6dQEq0w_5BeIEyag",
  "order_number": "1",
  "is_test": true,
  "status": "POS_VALIDATING",
  "statusHistory": [],
  "updated_at": "2021-12-02T17:29:16.877Z",
  "merchant_id": "-963301469",
  "fulfillment_info": {},
  "brand": "BRAND",
  "time_placed": "2021-12-02T17:29:16.877Z",
  "when_for": "2021-12-02T17:29:16.877Z",
  "restaurant_timezone_id": "UTC",
  "payments": {
    "total": 0,
    "adjusted_total": 0
  },
  "charges": {
    "fees": {
      "total": 0,
      "delivery": 0
    },
    "taxes": {
      "total": 0,
      "sales": 0,
      "delivery": 0,
      "restaurant": 0
    },
    "tip": {
      "amount": 0,
      "type": "INCLUDE_IN_BILL"
    },
    "diner_grand_total": 0,
    "grand_total": 0,
    "line_groups": [
      {
        "lines": [
          {
            "name": "food",
            "line_options": [
              {
                "price": 177,
                "id": "1152700327",
                "name": "salt",
                "line_sub_options": [
                  {
                    "id": "1352704759",
                    "name": "lots",
                    "price": 361,
                    "choice_category_id": "439607686"
                  }
                ],
                "quantity": 1
              }
            ],
            "price": 1899,
            "quantity": 34,
            "id": "946118396",
            "menu_item_id": "855724817",
            "item_type": "test",
            "variation_id": "1487364520"
          }
        ]
      }
    ],
    "coupons": []
  },
  "tax_withheld": false,
  "handoff_options": []
}

Request Change to Order

POST /pos/v1/merchant/{merchant_id}/orders/{order_uuid}/changerequests

Description

Request a change (cancellation, refund, upcharge, etc.) to an existing order.

Path Parameters

merchant_id

string

The short Grubhub ID for the restaurant.

order_uuid

uuid

The UUID of the order.

Body

body

OrderChangeRequest

The requested change to the order

Responses

200

OrderChangeRequestStatus

Get Status of Order Changes

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

Description

Returns the status of all order changes for a single order.

Path Parameters

merchant_id

string

The short Grubhub ID for the restaurant.

order_uuid

uuid

The UUID of the order.

Responses

200

List<OrderChangeRequestStatus>

Models

Address

Physical street address

Properties

address_line1

string

First address line

address_line2

string

Optional second address line

city

string

The city

state

string

The state as a two letter abbreviation

country

string

The country as a two letter abbreviation

zip_code

string

The zip code. This is a string because it may in certain cases contain a +4 zip.

latitude

double

The geolocated addresses latitude

longitude

double

The geolocated addresses longitude

cross_streets

string

The closest major cross streets as entered by the diner

Brand

The brand that the order was placed on

Type

string

Possible Values

GRUBHUB
SEAMLESS
YELP
GROUPON
EAT24
UNKNOWN

Catering

Catering details for an order

Properties

estimated_attendees

integer

Number of attendees

budget

integer

The budget they had for this order

alternate_name

string

Alternative contact info for the order

alternate_phone

string

Alternative contact info for the order

green_indicated

boolean

If set to true, the restaurant should not include napkins, utensils and other items that would just become waste as the diner has access to their own dishes and utensils

setup_food

boolean

If true, the driver should setup the food before leaving

setup_instructions

string

Instructions on how to setup the order

Change Action

The type of change action requested.

Type

string

Possible Values

adjust.action
cancel.action

Charges

Contains information about the contents of the order including the financial totals and items ordered.

Properties

fees

Fees

Fees for the order

taxes

Taxes

Taxes applied to the order

tip

Tip

Tip for the order

diner_grand_total

integer

Deprecated. Use "merchant_total" instead.

grand_total

integer

Deprecated. Use "merchant_total" instead.

merchant_total

long

The total charges for the order in US Cents. Sum of subtotal, fees, taxes and tips.

merchant_subtotal

long

Charges for all line items in US Cents. Excludes taxes, tips and fees.

line_groups

List<LineGroup>

The items ordered by the diner

coupons

List<Coupon>

Coupons applied to the order

Contact Info

Basic diner contact information

Properties

phone

string

Phone number of the diner. This number can only be used for the fulfillment of the order and may not be stored and used for any sort of marketing, research or other contacts not directly related to the delivery or pickup of this specific order.

name

string

Name of the diner

Coupon

Coupons applied to the order

Properties

text

string

Text identifying the coupon

amount

integer

The amount of the coupon in US Cents

Delivery Info

Delivery Information

Properties

string

An id for this delivery

address

Address

the address to deliver to

is_managed_delivery

boolean

This delivery will be provided by Grubhub and not by the restaurant

estimated_delivery_time

dateTime

The time that the delivery is estimated to occur

is_green_indicated

boolean

If set to true, the restaurant should not include napkins, utensils and other items that would just become waste as the diner has access to their own dishes and utensils

instruction

string

special instructions for delivery

contact_info

ContactInfo

Contact information for the diner

managed_delivery_delivered

dateTime

If this is a Grubhub managed delivery, the time that the food was delivered to the diner. If this is a managed delivery order and this value is not set, it is still not yet delivered to the diner.

managed_delivery_estimated_pickup

dateTime

If this is a Grubhub managed delivery, this indicates the time that the driver will be at the restaurant to pick up the food for ultimate delivery

order_delivery_type

OrderDeliveryType

This indicates whether food is delivered by Grubhub or the restaurant.

Fees

Base fees paid by the diner for the line items and delivery charges before taxes and tip

Properties

total

integer

Total of all fees in US Cents

delivery

integer

Delivery charges in US Cents.

Fulfillment Info

Information about how to fulfill the order. If delivery info is provided, this is a delivery order, otherwise this is a pickup order. Exactly one property will be set on this object as delivery and pickup are mutually exclusive and required for fulfillment.

Properties

delivery_info

DeliveryInfo

information on how to deliver the order to the diner

pickup_info

PickupInfo

information about the pickup of the order including basic diner information

Line

A line item for the order

Properties

description

string

A description of the line item

name

string

The name of the line item

special_instructions

string

Free form text special instructions added by the diner

line_options

List<LineOption>

The options selected

price

integer

Deprecated. Use "merchant_price" instead.

merchant_price

long

The price of this item in US Cents

quantity

integer

The number of this item to include

string

The Grubhub ID for this line item, may be null

menu_item_id

string

The Grubhub menu item ID (legacy_id)

menu_item_uuid

uuid

Grubhub menu item uuid.

diner_total

integer

The total cost of this item (and options) in US Cents

total

integer

The total cost of this item (and options) in US Cents

item_type

string

A categorization of this item

variation_id

string

DEPRECATED. A Grubhub Id for a specific variation of this line item

Line Group

A group of line items. Currently, the entire order is within one line group; as group ordering features are rolled out, orders will include multiple line groups.

Properties

label

string

A label for the group of line items. This will be used in the future for the name of a diner on a group order.

lines

List<Line>

The lines items for this portion of the order.

Line Sub Option

Sub Options that are applied to an Option or other Sub Option. These can be nested up to ten levels deep.

Properties

string

The Grubhub ID of the sub option.

name

string

The name of the sub option, which will be shown to diners.

price

integer

The additional price of this sub option in US Cents.

quantity

Integer

The amount of this option to add to the previous option. This can indicate combos (single menu items with multiple selectable items), options with variable amounts, or options that can be selected multiple times.

LineOption

Options applied to a Line Item

Properties

label

string

DEPRECATED. A label for this line item option

price

integer

The price of this line option in US Cents

string

A Grubhub id (legacy_id) for this option

name

string

The name of this option

line_sub_options

List<LineSubOption>

Sub-options applied to this option.

external_id

string

The external ID that was stored in Grubhub for this option

quantity

integer

The number of this line options to include

Order

The order model is the basis for all Grubhub orders. This contains all necessary information for fulfilling and processing orders.

Properties

uuid

UUID

The globally unique identity of the order. This is the primary and only guaranteed unique identity.

merchant_uuid

UUID

Grubhub UUID for the restaurant.

order_number

string

A more human-readable order number to show to the customer, restaurant and drivers. This is not guaranteed to be unique forever and is thus not used as a true identifier from an API perspective.

is_test

boolean

If true, this is a test order and should not actually be prepared

status

Status

The current state of the order, such as CONFIRMED, PICKUP_READY, or FULFILLED.

status_history

List<StatusUpdate>

A list of all status updates for this order

updated_at

dateTime

The last time the order was updated.

merchant_id

string

The short Grubhub ID for the restaurant.

fulfillment_info

FulfillmentInfo

Information required to fulfill the order. This contains basic customer information.

brand

Brand

Indicates which brand (Grubhub vs. Seamless) where the order originated

time_placed

dateTime

The time that the diner placed the order

confirmation_code

string

A string indicating the code required when confirming the order via a phone call. This is not required for programmatic confirmations of the order and can most likely be ignored.

when_for

dateTime

The time that the food should be delivered or in the case of a pickup order, ready for pickup

restaurant_timezone_id

DateTimeZone

The timezone of the restaurant

payments

Payments

Individual payments for the order, this will also include adjustments

charges

Charges

Individual charges for the order, this will also include adjustments

tax_withheld

Boolean

TRUE indicates that sales tax has been collected on behalf of the restaurant by GH

catering

Catering

Catering information

jit_enabled

Boolean

Indicates if the associated restaurant has enabled just-in-time preparation for this order, where orders will be prepared only when the driver comes within a specified distance. This does not indicate that the JIT event has fired, just that `just_in_time_fired` can be expected to indicate when the driver is close enough to prepare the order.

just_in_time_fired

Boolean

TRUE indicates that the driver is within the geofence distance and the restaurant should package the order for pickup.

fulfillment_scheduling

PosFulfillmentScheduling

Order fulfillment type

handoff_options

List<string>

Instructions around the handoff pertaining to contact-free delivery

order_merchant_id

UUID

Used within grouped orders to identify a portion of an order associated with a single merchant. Grouped orders can have menu items from multiple restaurants associated with a single order.

Example

{
    "uuid": "JylzkoC0Ee2zk-PUFdlLqg",
    "merchant_uuid": "0OfxgNelEey87BGSJG9AHg",
    "order_number": "604721063804098",
    "is_test": false,
    "status": "REJECTED",
    "statusHistory": [
        {
            "status": "REJECTED",
            "timestamp": "2022-12-20T22:46:01.582Z",
            "update_source": "CONFIRMATION_AUTOMATION"
        },
        {
            "status": "STALE",
            "timestamp": "2022-12-20T22:36:00.864Z",
            "update_source": "GRUBHUB_ORDERS_REAPER",
            "reason": "Stuck status RESTAURANT_CONFIRMABLE at 2022-12-20T22:36:00.864Z"
        },
        {
            "status": "RESTAURANT_CONFIRMABLE",
            "timestamp": "2022-12-20T22:18:07.810Z",
            "update_source": "TXS"
        },
        {
            "status": "ANTICIPATED",
            "timestamp": "2022-12-20T22:18:07.430Z",
            "update_source": "DINER",
            "reason": "non-GHD"
        }
    ],
    "updated_at": "2022-12-20T22:46:01.582Z",
    "merchant_id": "10004116752",
    "fulfillment_info": {
        "pickup_info": {
            "name": "John Doe",
            "contact_info": {
                "phone": "(222) 222-2222",
                "name": "John Doe"
            },
            "instructions": "",
            "is_green_indicated": true
        }
    },
    "brand": "GRUBHUB",
    "time_placed": "2022-12-20T22:18:06.214Z",
    "confirmation_code": "6335",
    "when_for": "2022-12-20T22:28:06.221Z",
    "restaurant_timezone_id": "America/New_York",
    "payments": {
        "payments": [
            {
                "payment_type": "CREDIT_CARD",
                "amount": 472,
                "tax_application": "POST_TAX"
            }
        ],
        "total": 472,
        "adjusted_total": 472
    },
    "charges": {
        "fees": {
            "total": 0,
            "delivery": 0
        },
        "taxes": {
            "total": 32,
            "sales": 32,
            "delivery": 0,
            "restaurant": 32,
            "merchant_sales_total": 32,
            "merchant_total": 32
        },
        "tip": {
            "amount": 0,
            "type": "CASH"
        },
        "diner_grand_total": 472,
        "grand_total": 472,
        "adjusted_grand_total": 472,
        "line_groups": [
            {
                "lines": [
                    {
                        "name": "Avocado Cherry Tomato",
                        "line_options": [],
                        "price": 440,
                        "merchant_price": 440,
                        "quantity": 1,
                        "menu_item_id": "2426676565",
                        "menu_item_uuid": "AAAAAAAAAAasdAkadss",
                        "diner_total": 440,
                        "total": 440,
                        "tags": [],
                        "external_id": "Salad|Avocado Salad",
                        "metadata": "{\"internal_id\":1123234}",
                        "routing_tags": [],
                        "line_uuid": "J5AkoIC0Ee2koy&8hjj",
                        "packaging_options": []
                    }
                ]
            }
        ],
        "coupons": [],
        "merchant_total": 472,
        "merchant_subtotal": 440,
        "restaurant_subtotal": 440,
        "merchant_subtotal_before_coupons": 440
    },
    "tax_withheld": true,
    "jit_enabled": true,
    "just_in_time_fired": false,
    "diners": [
        {
            "status": "ACTIVE",
            "diner_info": {
                "phone": "(222) 222-2222",
                "name": "John Doe"
            },
            "charges": {
                "fees": {
                    "total": 0,
                    "delivery": 0
                },
                "taxes": {
                    "total": 32,
                    "sales": 32,
                    "delivery": 0,
                    "restaurant": 32,
                    "merchant_sales_total": 32,
                    "merchant_total": 32
                },
                "tip": {
                    "amount": 0,
                    "type": "CASH"
                },
                "diner_grand_total": 472,
                "grand_total": 472,
                "adjusted_grand_total": 472,
                "line_groups": [
                    {
                        "lines": [
                            {
                                "name": "Avocado Salad",
                                "line_options": [],
                                "price": 440,
                                "merchant_price": 440,
                                "quantity": 1,
                                "menu_item_id": "2426676565",
                                "diner_total": 440,
                                "total": 440,
                                "tags": [],
                                "routing_tags": [],
                                "line_uuid": "J5AkoIC0Ee2koy&8hjj",
                                "packaging_options": []
                            }
                        ]
                    }
                ],
                "coupons": [],
                "merchant_total": 472,
                "merchant_subtotal": 440,
                "restaurant_subtotal": 440,
                "merchant_subtotal_before_coupons": 440
            },
            "payments": {
                "payments": [
                    {
                        "payment_type": "CREDIT_CARD",
                        "amount": 472,
                        "payment_source": "UNKNOWN",
                        "tax_application": "POST_TAX"
                    }
                ],
                "total": 472,
                "adjusted_total": 472
            },
            "order_diner_number": "1232132343",
            "cart_uuid": "JylzkIC0Ee2zkePUaHjs",
            "participation": "HOST"
        }
    ],
    "order_type": "STANDARD",
    "order_taking_system": "CARTING",
    "handoff_options": [],
    "restaurant_version_id": {
        "catalog_version": {
            "version_id": "v1:VoNHjJPBjGrXXThkLnOrrgVAmwBG3yR2"
        }
    },
    "fulfillment_scheduling": "ASAP",
    "transmission_id": "IwsfGSpHM461UOWnLXHf6g",
    "order_merchant_id": "9CvhTfZvNvqR8_WRGSjL9Q"
}

Order Change Request

Payload required to change an order state

Properties

amount

integer

Price change requested on the order in US Cents

restaurant_agent_name

string

Who is requesting the change. Should be the logged-in user at the POS. Displayed as a comment on the ticket

requestor_first_name

string

First name of the restaurant contact to be notified for ticket updates.

requestor_last_name

string

Last name of the restaurant contact to be notified for ticket updates.

requestor_email

string

Email address of the contact to be notified for ticket updates.

reason

string

A description of the reason for the change

notes

string

Additional notes

status_version_uuid

uuid

The version of the order to adjust

change_action

ChangeAction

The action to take

Order Change Request Status

Status of a submitted order change request.

Properties

order_id

UUID

Unique identifier for the order for which the change request was submitted.

change_request_id

UUID

Unique identifier for the change request that was created.

request

OrderChangeRequest

The change request.

status

string

The current status of the change request. One of `COMPLETE` or `PENDING`.

Order Delivery Type

This indicates whether food is delivered by Grubhub or the restaurant.

Type

string

Possible Values

GRUBHUB
SELF

Payment

A single payment source

Properties

payment_type

string

The payment type. Note all non-CASH payment types should be treated as pre-paid to a Grubhub tender or house account in the POS.

amount

Integer

The payment amount in US Cents

tax_application

String

Whether this payment is applied `POST_TAX`, `PRE_TAX`, or that the tax applied to this payment is`UNKNOWN`. Most payment types will be applied `POST_TAX`; however, loyalty rewards are applied by the merchant and therefore lower the taxable amount of the order. These payments from the merchant will generally be listed as `PRE_TAX'.

payment_source

String

Where this payment came from. Possible values are `DINER`, `MERCHANT`, `GRUBHUB`, `OTHER`, or `UNKNOWN`. Note that `MERCHANT` payments are usually loyalty reward discounts and reduce the taxable total of a given order.

Payments

Payments on the order

Properties

payments

List<Payment>

A payment source

total

integer

Initial total for an order in US Cents

adjusted_total

integer

Total payments after adjustments in US Cents

Pickup Info

Information about the pickup order

Properties

name

string

The name of the person coming to pickup the order

contact_info

ContactInfo

Contact information for the diner

instructions

string

Special instructions for pickup

estimated_pickup_time

dateTime

The time that the diner was told that their food would be available for pickup.

is_green_indicated

boolean

if set to true, the restaurant should not include napkins, utensils and other items that would just become waste as the diner has access to their own dishes and utensils

PosFulfillmentScheduling

Order fulfillment type.

Possible Values

ASAP
FUTURE
UNKNOWN

Reason Code

Status update reason code. Currently used only for updating status to REJECTED.

Type

string

Possible Values

RESTAURANT_OFFLINE
MENU_ITEM_NOT_FOUND
PRICE_MISMATCH
OTHER

Security for Order Validation

Callback url is expected to use HTTPS, enforced at registration time (Partner Accounts).

Type

authorization

Possible Values

None = No authorization sent with webhook request.
Basic = Basic auth credentials using username and password
HMAC = Client Id, Client Secret, and issue Date used in construction of MAC header. Initial implementation identical to our internal server-to-server tokens.
OAuth2 = client_credentials flow supported. Client Id and Secret are used to obtain an access token, which is used for subsequent webhook requests. A leader elected process will support maintaining a valid access token for each OAuth2 integration.

Status

The status of an order as it passes through the Grubhub fulfillment flow.

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

Status Update Request

Payload to request a status change

Properties

status

Status

New Status

wait_time_in_minutes

long

When using this to confirm an order, this should represent the remaining wait time in minutes. If this is a pickup order, it is the number of minutes before the food is ready for pickup. If this is a delivery order, it is the estimated number of minutes until delivery to the diner. If it is a Grubhub Managed Delivery order, it the estimated number of minutes until the food is ready for pickup by the Grubhub delivery driver.

reason_code

ReasonCode

Required only if updating status to REJECTED. Reason for rejecting the order.

message

string

If updating status to REJECTED, descriptive text `IS REQUIRED` to providing more detail about the rejection reason. This information may be included in logging and customer care tickets. Helpful information would be, for example, the ID of the menu item not found, or details on the price mismatch.

sub_total

integer

This is the updated subtotal amount in cents

tax_total

PosTaxTotal

Corrected tax for this this order.

Example

{
  "status": "CONFIRMED",
  "wait_time_in_minutes": 60,
  "tax_total": {
    "tax" : 3,
    "type": "ABSOLUTE"
  }
  "sub_total": 2345
}

StatusUpdate

A status update reflects each successive change in the status of an order.

Properties

status

Status

The status of order during that change

timestamp

dateTime

The time that the status changed.

update_source

UpdateSource

The source of the update.

reason

string

An optional reason for the update.

Tax total

Corrected tax for an order.

Properties

tax

Integer

The value of the tax. Depending on the type, this is either the updated tax amount in cents or the amount, in cents, that the Grubhub-calculated tax is off by.

type

String

Whether to set the tax using an ABSOLUTE value - the tax will be set to the amount specified - or RELATIVE - the tax will be adjusted by the tax value.

Taxes

Taxes paid by the diner

Properties

total

integer

Total tax paid

sales

integer

Tax portion attributed to sales tax

delivery

integer

Tax portion attributed to delivery fees

restaurant

integer

Tax portion accruing to the restaurant. For Grubhub Managed Delivery restaurants, this excludes delivery tax.

Tip

Information about tip. Note that tip may not be included in bill

Properties

amount

integer

Total tip in US Cents

type

TipType

The payment method for tip. If this is CASH, it must be collected upon pickup or delivery

Tip Type

Whether the tip was included in the bill (i.e., prepaid) or to be collected in cash.

Type

string

Possible Values

CASH
INCLUDE_IN_BILL
UNKNOWN

Update Source

Source of a status update in the status history.

Type

string

Possible Values

DINER
RESTAURANT
GRUBHUB
UNKNOWN

Validate Order Webhook Response

The current state or result of a menu ingestion job. Each status will be communicated with both a standardized status string and a human-readable description.

Properties

updated_status

string

Needs to either of the following "POS_VALIDATED" or "POS_VALIDATION_REJECTED"

reason_code

string

If you set the status to "POS_VALIDATION_REJECTED" you must also provide a reason_code. This code can be one of the following "RESTAURANT_OFFLINE", "MENU_ITEM NOT_FOUND", or "OTHER"

Empowering Restaurants through Integration

Orders

Basic Workflow

Order Validation

Order Validation Workflow

Order Validation Webhook Specification

Paths

Get Orders By Merchant, Status and Date Range

Get Orders By Group, Status and Date Range

Get Order by UUID

Update Order Status

Order Validation Outgoing Webhook

Request Change to Order

Get Status of Order Changes

Models

Address

Brand

Catering

Change Action

Charges

Contact Info

Coupon

Delivery Info

Fees

Fulfillment Info

Line

Line Group

Line Sub Option

LineOption

Order

Order Change Request

Order Change Request Status

Order Delivery Type

Payment

Payments

Pickup Info

PosFulfillmentScheduling

Reason Code

Security for Order Validation

Status

Status Update Request

StatusUpdate

Tax total

Taxes

Tip

Tip Type

Update Source

Validate Order Webhook Response