Empowering Restaurants through Integration

  1. Grubhub Developers
  2. Grubhub Partner Integration V2
  3. API Specification
Follow

FAQ

Frequently Asked Questions

Merchant Schedules

What time format should I use for the following?

(DateTime, DateTimezone, LocalDateTime, LocalTime, LocalDate)
UTC date time form are used for these fields, 
ex.  "2022-03-25T04:00:00.000Z", "9999-12-31T23:59:59.999Z"

Sample payload to set special hours e.g: if store opens up 10am-12pm (instead of normal 8am-8pm).
References:

Merchant Schedule Override

Merchant Override Definitions

"start": "2021-12-22T08:00",
"end": "2021-12-22T10:00",
"type":"UNAVAILABLE"

"start": "2021-12-22T12:00",
"end": "2021-12-22T20:00"
"type":"UNAVAILABLE"

Do I need to manually delete overrides (holiday hours) which are in the past?

No, because you are including a Date with the Time, the override will expire at the specified "end"


Is it possible to update an existing schedule overrides? If yes, how?

To update an existing Schedule Override Schedule, you will have to delete it first, and replace the current Override Schedule with a new one.

The schedule_id field will be the external_id for the repeating_schedules and you will use the value and place it on the menu/item/option level:

"repeating_schedules": [
  {
    "external_id": "5132ab87-e873-4804-8dfb-c5778668a006",
    "name": "Restaurant Hours",
    "type": "WEEKLY",
    "rules": [
      {
        "days_of_week": [
            "MONDAY"
        ],
        "start_time": "10:45:00.000",
        "end_time": "14:45:00.000"
      }
    ],
    "menu_sections": [
      {
      "external_id": "a97d1505-b844-455a-9395-4008c1389b91",
      "name": "TEST SECTION",
      "description": "123",
      "items": [
      "abc123test"
      ],
      "schedule_ids": ["5132ab87-e873-4804-8dfb-c5778668a006"]
      }
    ]
  }
]

If there are frequent restaurant hour changes, and I need to sync the hours to GrubHub daily. Which API do I need to use to post the hours daily ? Can I use the "Update merchant schedule" API (PUT /pos/v1/merchant/{merchant_id}/schedules/repeating) & does it take care of both creation & updating existing hours?

Yes this call will update both sets of hours


If a restaurant is closed permanently (or) temporarily closed (ex: power outage or weather or any repairs), is there a way we can mark the restaurant as closed in an automated manner? Which API do we need to invoke to close the restaurant?

Yes you can use this endpoint


If I use the "closenow" API to close the store, does the store automatically get re-enabled the next business day based on scheduled hours set? Ex: If the trigger "closenow" is set at 6 PM today, does the store open automatically tomorrow during the scheduled window?

Yes, the trigger is only for the current business day


If I use the "opennow" API to open the store, does the store open & starts accepting orders even though the time is outside the scheduled hours (ex: scheduled hour is 10 AM to 9:30 PM).

Yes, the store will start accepting orders right away


Which API can I use to set up special day /custom hours (ex: ThanksGiving, Christmas Eve, Christmas hours)?

You can use the add schedule override endpoint


Does GrubHub have a buffer/cut-off time to close the restaurants?

Yes, the buffer time for restaurants is 30 min at the end of day and 15 mins at the start of day. If the restaurant opens at 10:00 am, the first available order for pickup is 10:15 am. If the restaurant closes at 11:00 pm the last pickup available will be 10:30 pm.


Does the hours set in the Merchant portal override the hours set with an API call?

No


Menus

If I upload a default tax_rate for every menu item, which amount of tax will diners see before the payment?

The diners will see the tax rate that is uploaded on each menu item during checkout


What time format should I use for menus?

24 hour time format, it should be similar to this example:


    {
        "days_of_week": [
            "SUNDAY"
        ],
        "start_time": "09:00:00.000",
        "end_time": "23:00:00.000"
    }

Is the order of the items in the arrays of sections and menu items respected when displayed on the menu?

Yes, the order is respected.


What is "modifier_quantity_settings" & how is it different from "modifier_prompt_quantity_settings"?

"modifier_quantity_settings" is setting for individual modifier while "modifier_prompt_quantity_settings" is to define min/max for the modifier group itself


Does Grubhub support modifier images?

Yes



Ordering

When is order cancellation available for the customer?

The only time when order cancellation is available for a customer is for scheduled orders, prior to the RESTAURANT_CONFIRMABLE order webhook. More information on Order Statuses can be found HERE


Can a provider modify an order after submission?

Grubhub Care can operationally process partial refunds/refunds should the provider/restaurant or a driver calls


Can I set estimated delivery times by zone for Self-delivery?

For self delivery time you set a default prep time and then an estimated delivery time which is inclusive of prep and delivery time (ex: 30 minutes total). These are static as 1 number, not a range (ex. 12-20 minutes)


Can future orders be turned off?

Future ordering can be turned off by using this endpoint


Ordering

How often can we change the delivery estimate and minimum?

Merchant Data can be updated as frequently as you’d like.


If a courier arrives at the delivery address but can’t contact the client, what should I do?

It's best to call Care for assistance and also send a changeOrder request.


Does a self-delivery courier know if an order is from Grubhub or not?

Self-delivery couriers are not required to know if a delivery is for a Grubhub diner.


Taxes

How can the provider set additional taxes/fees?

  • Store level tax rates can be set via the "Update Tax Rates" in the Merchant Data API
  • Item-level tax rates should be included in the normalized menu structure.

Can I supply “merchant level tax” and only send the real total tax at the time of the order?

Yes if you’ll be adding item level tax rates to your menus and if you are sending back adjusted tax/subtotal if it does not match what we send. The diner will see an order adjustment due to the delta between Merchant level tax rate and order submission.


Can I correct the order taxes after submitting?

Yes you will use the Order Status Update endpoint to update. Note: We require “type” to be ABSOLUTE


If a diner refuses to take one product from the order at the end of delivery, the customer usually calls Grubhub Care to make partial reimbursement. Is it possible to use API change request before the delivery is finished?

  • There is no time limit set by Grubhub for “CONFIRMED” orders. Currently, this has two possible actions (ADJUST or CANCEL):
  • For confirmed orders, the provider can "ADJUST" the order with no time restrictions.
  • Should the provider wish to “CANCEL” an order, this action cannot be undone.


Miscellaneous

What types of Customer Support do Diners have?

  • Customer calls Grubhub
  • Customer calls restaurant
  • Restaurant calls Customer

Could I use order pre-checkout validation to check our stock?

Yes, you can use this to inform us that items are not in stock, thereby prohibiting order for being confirmable for diner. We will send the order validation request for every addition or removal of a menu item. This means you should expect several order validation requests for a given active cart on Grubhub Marketplace. Grubhub will expect an appropriate response for each validation webhook.


How will Grubhub inform providers about refunds?

The Financials section in the Grubhub for Restaurants portal is where you can view transaction details and see summary views of your restaurant’s financial health. You can change the reporting period for more detailed summary views as well as download reports as CSVs to do additional analysis. You may also sign up for Daily Transactions Summaries, this report is sent 15 minutes after closing time and includes the transactions/orders that were placed for that same day.

If you'd like to sign up to receive Daily Transaction summaries simply go to the Financials → Transactions tab in Grubhub For Restaurants, under “View Transactions”, click the checkbox next to “Send me a daily transaction summary email”. Additionally Grubhub will notify the restaurant via the primary contact email on file. You can also view all transactions and cancellations on the merchant portal.


Is it possible to make partial refunds or only full refunds are available?

Partial refunds are available by contacting elitecare@grubhub.com


Is it possible to refund tips only?

Yes


Can tips be turned off for Pickup Orders?

Yes


How long is the payment refund available for a customer?

Some financial institutions can take up to 5 days to process a refund.


Process of reconciliations, what is the process of reconciliations?

Please send future credit requests directly to our Restaurant Care department at restaurants@grubhub.com . We kindly ask that you submit your requests within 7 days of the discrepancy.

What about technical implementation?

Grubhub does not support reconciliation via API/integration at this time.


If we reject order pre-validation with a reason "POS_VALIDATION_REJECTED", what will the client see? Will an item be skipped?

Diners will not be able to place this order, however they can go back to cart and add/remove items to retry when Grubhub will send another POS Validation webhook to the provider. Diners are not allowed to place orders that are POS_VALIDATION_REJECTED.


When will the diner pay for the order? After order confirmation (status = CONFIRMED) or before (status = RESTAURANT_CONFIRMABLE)?

The diner pays after the Order is fulfilled. Grubhub does a VISA hold on diner’s payment method after order is CONFIRMED


Can the same target webhook url be used for both orders and delivery updates? And JIT events?

Yes. However, we do have the capability to have separate URLs for each of those.


What are the header_media image requirements?

Header Image Specifications:

  • Displays as a 4:1 aspect ratio
  • If a 4:3 aspect ratio image is provided, the image is then automatically zoomed and cropped to 4:1 ratio in Grubhub content system
  • At least 2400x600 pixels
  • Saved as a .jpeg file

What is Grubhub+?

  • Grubhub+ is a diner subscription service that unlocks unlimited free delivery from qualified restaurants and storefronts in their area. (see landing page here)
  • Value of Grubhub+ for providers:
    • Grubhub+ subscribers represent our highest LTV diners. Brands that participate in Grubhub+ gain greater visibility among our highest-value, highest-frequency diners. We indicate participating brands with the yellow Grubhub+ icon in Marketplace listings.
  • Benefits of Grubhub+ for Diners:
    • Free delivery at participating restaurants (on orders over $12)
  • Elite Diner Care
  • Donate the Change matching
  • VIP offers, events, and experiences
  • Watch Grubhub+ Video here
  • Grubhub+ Overview here

Will Grubhub pass diners' phone numbers to the provider?

Grubhub is working on the ability to mask diner phone numbers prior to sending to the provider. Timeline on this support is TBD.


How do we coordinate passing secrets and keys?

We use https://privnote.com/


Are there separate tokens for dev vs prod, or does Grubhub just want to use one token?

We use separate tokens for dev and pre production.


What is partner_id? (iex, /pos/v1/merchant/{partner_id}/idmappings)

The partner_id is the same as the partner key, which should be supplied in the credentials that were provided to you. If you do not have them please contact your representative.

Paths

Models