Merchant Data
The merchant data component provides basic information about restaurants and groups of restaurants. In the future, this component will be extended to allow for updating a merchant's Grubhub account information (e.g., delivery fees).
Paths
Get Merchant by Merchant ID
GET /pos/v1/merchant/{merchant_id}Returns summary information about a merchant. Will be extended in the future.
Get Configuration Group
GET /pos/v1/config/groups/{group_key}Returns a configuration group, including the merchant IDs included in the group. This group key can be used for polling orders and deliveries to avoid making separate requests for each merchant.
Get Internal / External ID Mappings
GET /pos/v1/merchant/{partner_id}/idmappingsReturns the internal / external merchant ID mappings associated with your partner_id (which a customer includes in every API call),
for either up to 100 external restaurant IDs (if the externalIds query parameter is populated and valid)
or ALL the internal / external restaurant IDs (when the externalIds query parameter is not populated or not sent at all).
You will have to have ingested a menu before this endpoint will return valuable information.
[
{
"partner_id": "XXXXXXXXXX",
"internal_id": "12110000",
"external_id": "1235",
"type": "merchant"
},
{
"partner_id": "XXXXXXXXXX",
"internal_id": "12110001",
"external_id": "1236",
"type": "merchant"
}
]
Get Fulfillment Info by Merchant ID
GET /pos/v1/merchant/{merchant_id}/fulfillmentReturns a merchant's fulfillment info.
Get the delivery minimum by Merchant ID
GET /pos/v1/merchant/{merchant_id}/deliveryminimumReturns the merchant's delivery minimum.
Update the delivery minimum by Merchant ID
PUT /pos/v1/merchant/{merchant_id}/deliveryminimumUpdates a merchant's delivery minimum if they do not do managed delivery.
(Deprecated) Get the delivery fee by Merchant Id
GET /pos/v1/merchant/{merchant_id}/fulfillment/deliveryfeeReturns the merchant's delivery fee.
(Deprecated) Update the delivery fee by Merchant Id
PUT /pos/v1/merchant/{merchant_id}/fulfillment/deliveryfeeUpdates a merchant's delivery fee if they do not do managed delivery.
Get delivery area fee by Merchant Id
GET /pos/v1/merchant/{merchant_id}/fulfillment/{delivery_area_id}/deliveryfeeReturns the merchant's delivery fee for the area.
Update delivery area fee by Merchant Id
PUT /pos/v1/merchant/{merchant_id}/fulfillment/{delivery_area_id}/deliveryfeeUpdates a merchant's delivery fee for specified area.
Get the delivery areas for a merchant
GET /pos/v1/merchant/{merchantId}/fulfillment/deliveryboundariesReturns the merchant's delivery boundaries.
Update the delivery boundaries by Merchant ID
PUT /pos/v1/merchant/{merchantId}/fulfillment/deliveryboundariesUpdates a merchant's delivery boundaires if they have delivery settings configured. Note that the body of this request must include the entire set of all delivery areas, as this change overwrites all current delivery zones. For example:
[
{
"name": "Delivery Area 1",
"fee_cents": 899,
"zone_type": "DINER",
"geometry": "{\"type\":\"Polygon\",\"coordinates\":[[[-86.743567,34.827408],[-86.814128,34.811865],[-86.86572,34.769414],[-86.884518,34.711461],[-86.865549,34.653548],[-86.813957,34.611179],[-86.743567,34.595676],[-86.673177,34.611179],[-86.621585,34.653548],[-86.602616,34.711461],[-86.621414,34.769414],[-86.673006,34.811865],[-86.743567,34.827408]]]}"
},
{
"name": "Delivery Area 4",
"fee_cents": 799,
"zone_type": "DINER",
"geometry": "{\"type\":\"Polygon\",\"coordinates\":[[[-86.741867,34.611736],[-86.802292,34.624733],[-86.848984,34.661452],[-86.865463,34.710574],[-86.849327,34.762205],[-86.803665,34.798581],[-86.74324,34.812112],[-86.682816,34.798581],[-86.636575,34.761204],[-86.621704,34.71142],[-86.638184,34.661452],[-86.680756,34.626428],[-86.741867,34.611736]]]}"
},
{
"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]]]}"
}
]
Update fulfillment estimates
PUT /pos/v1/merchant/{merchant_id}/fulfillment/estimatesUpdates the estimated time that the restaurant takes to fulfill an order for both pickup and delivery, separately.
Get fulfillment estimates
GET /pos/v1/merchant/{merchant_id}/fulfillment/estimatesReturns the estimated time that the restaurant takes to fulfill an order for both pickup and delivery, separately.
Update Pre-order confirmable window (in minutes).
PUT /pos/v1/merchant/{merchantId}/preorderwindowThe Pre-order confirmable window determines when Grubhub should transition a scheduled order from ANTICIPATED status to RESTAURANT_CONFIRMABLE with relation to the desired fulfillment time. For example, a merchant with a window of 120 minutes would receive the RESTAURANT_CONFIRMABLE webhook 2 hours before desired fulfillment time giving them plenty of time to prep the order. For restaurants with faster prep time, this window is usually very small to guarantee food quality.
Update tax rates
PUT /pos/v1/merchant/{merchant_id}/taxrateUpdates the overall tax rates for a merchant. These rates will be used for any menu item or other taxable charge that does not have its own tax rate configuration.
Get tax rates
GET /pos/v1/merchant/{merchant_id}/taxrateReturns the overall tax rates for a merchant. These rates will be used for any menu item or other taxable charge that does not have its own tax rate configuration.
Toggle scheduled ordering capability for a merchant.
PUT /pos/v1/merchant/{merchant_id}/scheduledordersAllows an individual merchant to opt in/out of scheduled ordering.
Fetch Grubhub tax categories that can be applied on a menu.
GET /pos/v1/tax-categoriesFetch Grubhub internal tax classifications.
Set Restaurant Online/Offline for an individual merchant
PUT /pos/v1/merchant/{merchant_id}/pos-statusProvides the ability to set a restaurant online/offline on Grubhub. When offline, the restaurant will not be listed on the site; when online, the restaurant will be listed on the site and be able to accept orders.
Set Restaurant Online/Offline for a batch of merchants
PUT /pos/v1/merchant/pos-statusProvides the ability to set a batch of restaurants online/offline on Grubhub. When offline, the restaurant will not be listed on the site; when online, the restaurant will be listed on the site and be able to accept orders.
Get Restaurant Online/Offline Batch Status
GET /pos/v1/merchant/pos-status/{batch_id}/statusReturns the status of the merchant online/offline batch together with the progress for each individual merchant, or, if present, only for the specified merchant ID.
Batch Update Merchant Live Integration Status
PUT /pos/v1/merchant/integrationliveEnables / disables live integration status for a batch of merchants. A merchant can have live integration enabled only if it has at least one successful ingestion completed and it's not a GH Direct merchant.
Get Merchant Live Integration Batch Status
GET /pos/v1/merchant/integrationlive/{batch_id}/statusReturns the status of the merchant live integration batch together with the progress for each individual merchant, or, if present, only for the specified merchant ID.
Batch Update Merchant properties.
PUT /pos/v1/merchant/propertiesUpdates Merchant properties for multiple merchants or individual merchant at a time.
Get Merchant Properties Update Batch Status
GET /pos/v1/merchant/properties/{batch_id}/statusReturns the status of the merchant properties update batch together with the progress for each individual merchant, or, if present, only for the specified merchant ID.
Models
Account Status
The status of the merchant on Grubhub.
Address
Physical address.
Bulk Processing status associated to a merchantID
Merchant ID and their bulk processing status, including additional information in case of NOT_FOUND / INVALID statuses.
{
"merchant_id": "111111",
"status": "NOT_FOUND",
"details": "Merchant with ID=111111 not found."
}
{
"merchant_id": "222222",
"status": "SUCCESSFUL",
}
Config Group
A group of merchants sharing a common POS configuration in Grubhub. E.g., Merchants who are configured for POS Partner X.
Delivery Area
Delivery area configuration settings.
Delivery Area Fee
Value of the fee that is applied to an order for the delivery service.
integer
Delivery Fee
A fee that is applied to a merchant for the delivery service.
Delivery Minimum
The minimum dollar value a merchant requires for an order to be eligible for delivery.
Double
Estimates
Pickup and delivery estimates.
External ID map
Information about internal merchant ID mappings for an external_id.
Fulfillment estimate
Estimated pickup and delivery times for a restaurant.
Fulfillment estimate request
Estimated pickup and delivery times for a restaurant.
Geo Location
Latitude and longitude coordinates for a location.
Get tax categories response
The Grubhub Tax Classification Model.
Merchant
Summary information about a merchant. This entity will be expanded over time.
Merchant Batch Operation Response
Reference ID to a batch of merchant operation requests and all the associated merchant IDs.
Merchant Batch Operation Status
Describes the state (completed or not) of an entire batch of merchant operation requests together with the status of each individual request associated to this batch.
{
"batch_id": "T58amO2BRYqV6-HD0hb2Aw",
"processing_complete": true,
"merchant_status": {
"100000": "SUCCESSFUL",
"111111": "NOT_FOUND",
"222222": "INVALID",
"333333": "FAILED",
"444444": "FAILED_TO_QUEUE",
"555555": "IN_PROGRESS",
"666666": "REQUESTED"
},
"merchant_statuses": [
{
"merchant_id": "100000",
"status": "SUCCESSFUL"
},
{
"merchant_id": "111111",
"status": "NOT_FOUND",
"details": "Merchant with ID=111111 not found."
},
{
"merchant_id": "222222",
"status": "INVALID",
"details": "Request to update merchant is invalid for merchantId=222222; validation errors: [client errors will go here]"
},
{
"merchant_id": "333333",
"status": "FAILED"
},
{
"merchant_id": "444444",
"status": "FAILED_TO_QUEUE"
},
{
"merchant_id": "555555",
"status": "IN_PROGRESS"
},
{
"merchant_id": "666666",
"status": "REQUESTED"
}
]
}
Merchant Fulfillment Info
Contains pickup and delivery info for a merchant.
Merchant Live Integration Request
Pair of merchant ID and its desired live integration status - true / false.
Merchant Property Type
Multiple properties or settings associated with Merchant ID/s. These are the possible properties that Merchant ID/s can have or update.
{
"delivery_estimate_minutes" : 25,
"pickup_estimate_minutes" : 45,
"Sales_Tax" : 2.8,
"driver_pickup_instructions" : "pickup instructions",
"special_instructions_disabled" : true,
"diner_pickup_contact_phone" : "9738746731",
"diner_offers_curbside_pickup" : true,
"diner_pickup_curbside_instructions" : "Sunny Street, 123"
}
Merchant Property Update Request
Merchant ID/s and properties to update for multiple merchants or individual merchant at a time.
{
"merchant_ids": ["11111111","22222222"],
"property_updates": {
"driver_pickup_instructions": "pickup instructions",
"special_instructions_disabled": true,
"sales_tax":1.9,
"pickup_estimate_minutes":25,
"diner_pickup_contact_phone":"9738746731",
"diner_offers_curbside_pickup":true,
"diner_pickup_curbside_instructions":"Sunny Street, 123"
}
}
Merchant Service Type
Configurations in which the restaurant is able to provide food to the diner.
MerchantPosStatusRequest
Request to set restaurant status online or offline.
Order Processing Info
Contains order processing info of a merchant.
PosStatus
Restaurant status, whether online/offline.
string
- ONLINE
- OFFLINE
PosStatusRequest
Request to set restaurant status online or offline.
Pre-order window (in minutes)
The Pre-order confirmable window determines when Grubhub should transition a scheduled order from ANTICIPATED status to RESTAURANT_CONFIRMABLE with relation to the desired fulfillment time. For example, a merchant with a window of 120 minutes would receive the RESTAURANT_CONFIRMABLE webhook 2 hours before desired fulfillment time giving them plenty of time to prep the order. For restaurants with faster prep time, this window is usually very small to guarantee food quality.
integer
ScheduledOrdersUpdateRequest
Request to opt-in/opt-out from scheduled orders.
Tax rate
The tax rate for a merchant.
Double