Empowering Restaurants through Integration

  1. Grubhub Developers
  2. Grubhub Partner Integration V2
  3. Using the POS API
Follow

Configuring Merchant Accounts

While a POS integration interacts with Grubhub through menus and orders, that interaction can also configure some merchant-level information. This information applies across all orders by default.

Here's the merchant-level information you may want to allow your users to configure:

  • Delivery minimum.
  • Delivery fees.
  • Delivery boundaries.
  • Pickup and delivery estimates.

A restaurant using your POS integration could change this information at any time, but they should set these at least once (or understand the default values) before fulfilling orders.

Set Delivery Minimum

The delivery minimum is the value of all menu items in a diner's Grubhub order required before they can request it to be delivered to them. This minimum prevents the cost of a delivery exceeding the value of the items sold. A restaurant does not need to have a delivery minimum, so if this value is not set, it will default to zero.

To set this value, call PUT /merchant/{merchant_id}/deliveryminimum with just the minimum dollar value as the request body. It should look something like this:

PUT /pos/v1/merchant/503736/deliveryminimum HTTP/1.1
Host: api-third-party-gtm.grubhub.com
Content-Type: application/json
Authorization: MAC id="sv:v1:xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",nonce="xxxxxxxxxx:xxxxxx",mac="xxxxxxxxxxxxxxxx/U="
X-GH-PARTNER-KEY: xxxxxxxxxxxxxxxx

17.00

If successful, this endpoint will just return the delivery minimum value.

This same endpoint can be used with a GET request method to retriever the currently stored values.

Set Delivery Fee

A delivery fee is an extra charge added to any delivery order. While a restaurant does not need to set a delivery fee, those that do will need a way to integrate that information into their receipts and other tickets and incorporate that fee into their accounting.

To set the delivery fee, call PUT /merchant/{merchant_id}/fulfillment/deliveryfee with the type of fee - FLAT or PERCENT - and the value of the fee as either a dollar amount or percentage. The request should look something like this:

PUT /pos/v1/merchant/503736/fulfillment/deliveryfee HTTP/1.1
Host: api-third-party-gtm.grubhub.com
Content-Type: application/json
Authorization: MAC id="sv:v1:xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",nonce="xxxxxxxxxx:xxxxxx",mac="xxxxxxxxxxxxxxxx/U="
X-GH-PARTNER-KEY: xxxxxxxxxxxxxxxx

{
	"value": 2,
	"type": "FLAT"
}

If successful, the request will return the fee information as you sent it.

This same endpoint can be used with a GET request method to retriever the currently stored values.

Configure Delivery Boundaries

Delivery boundaries define the absolute edges of where a restaurant will deliver food. To allow maximum flexibility, we define boundaries using multiple GeoJSON strings, so a restaurant can define where they deliver using precision edges and non-contiguous regions.

Unlike the previous two items, delivery boundaries do not have a default value. All restaurants must set this value before accepting delivery orders.

To set delivery boundaries, call PUT /merchant/{merchantId}/fulfillment/deliveryboundaries with an array of GeoJSON strings that define individual polygons. Each of these polygons must contain the restaurant, so your POS integration must be able to handle when they don't.

This can be tricky - here's an example of what that can look like:

PUT /pos/v1/merchant/503736/fulfillment/deliveryboundaries HTTP/1.1
Host: api-third-party-gtm.grubhub.com
Content-Type: application/json
Authorization: MAC id="sv:v1:xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",nonce="xxxxxxxxxx:xxxxxx",mac="xxxxxxxxxxxxxxxx/U="
X-GH-PARTNER-KEY: xxxxxxxxxxxxxxxx

[
             {
                 "name": "Delivery Area 1",
                 "fee_cents": 599,
                 "zone_type": "DINER",
                 "geometry": "{\"type\": \"Polygon\",\"coordinates\":[[[-86.13899230957031,42.77977933922529],[-86.12560272216797,42.757411324122444],[-86.07590675354004,42.76175954256288],[-86.0940170288086,42.7913067382953],[-86.10843658447266,42.79590450075042],[-86.13899230957031,42.77977933922529]]]}"
             },
             {
                 "name": "Delivery Area 3",
                 "fee_cents": 799,
                 "zone_type": "DINER",
                 "geometry": "{\"type\":\"Polygon\",\"coordinates\":[[[-86.742897,34.639987],[-86.786842,34.649308],[-86.818085,34.675853],[-86.830788,34.711138],[-86.818771,34.747537],[-86.787186,34.773768],[-86.744614,34.782792],[-86.700325,34.773486],[-86.668053,34.747537],[-86.65638,34.711703],[-86.668053,34.67557],[-86.698608,34.650438],[-86.742897,34.639987]]]}"
             },
             {
                 "name": "Delivery Area 2",
                 "fee_cents": 699,
                 "zone_type": "DINER",
                 "geometry": "{\"type\":\"Polygon\",\"coordinates\":[[[-86.742897,34.668511],[-86.769505,34.6743],[-86.788902,34.690251],[-86.79594,34.711561],[-86.788902,34.733149],[-86.769676,34.749088],[-86.743927,34.754448],[-86.717663,34.748947],[-86.698437,34.733007],[-86.691227,34.71142],[-86.698265,34.689969],[-86.718178,34.674159],[-86.742897,34.668511]]]}"
             }
         ]

Note that the geometry objects are strings that contain a JSON object, so all quote characters must be preceded by an escape character. On success, this request will return the delivery boundary array that you passed.

This same endpoint can be used with a GET request method to retriever the currently stored values.

Set Pickup and Delivery Estimates

These estimates indicate to both diners and delivery drivers (when Grubhub manages the restaurant delivery service) how long food will take to be ready. The more accurate these estimates are, the happier customers will be. So precise estimates are key to customer satisfaction.

Set the default pickup and delivery estimates by calling PUT /pos/v1/merchant/{merchant_id}/fulfillment/estimates with the number of minutes pickup and/or delivery orders will take. Here's an example:

PUT /pos/v1/merchant/503736/fulfillment/estimates HTTP/1.1
Host: api-third-party-gtm.grubhub.com
Content-Type: application/json
Authorization: MAC id="sv:v1:3ac6e950-9d48-11e7-8a53-a10131b3b9e9",nonce="11605393026:qdOp52Sf",bodyhash="GSCrWghKNWqAkdNF2+dI+F4q0vUX7B+ygIbjkRy5rgM=",mac="JycU6Gy28Lua1TImtCbhBF68H5m8M379QchO1ZDqroQ="
X-GH-PARTNER-KEY: JL7ggIRiEeezDfVXVT1VHA
Cache-Control: no-cache

{
	"pickup_estimate_minutes": 20,
  "delivery_estimate_minutes": 45
}

If successful, the request will return the estimate information as you sent it.

This same endpoint can be used with a GET request method to retriever the currently stored values.

Pausing Online Ordering

If a restaurant needs to temporarily remove itself from being available on the Grubhub, say due to a high volume of orders or a shortage of staff, there's a single endpoint that will mark them as closed immediately, regardless of their current business hours: POST /pos/v1/merchant/{merchant_id}/schedules/closenow

While this endpoint uses a POST method, it does not need any content in the request body. The merchant_id in the path is information enough.

Similarly, to restart ordering, call POST /pos/v1/merchant/{merchant_id}/schedules/opennow. Both of these endpoints will override whatever the current schedule is, including schedule overrides. The manual override will last until the next scheduled change of status.