Adding order fulfillment time & fees for Food Ordering action links

This tutorial walks through:

  1. A high level description of how order fulfillment time and fees is shown to the user, and what type of data is required
  2. Specific instructions on how to specify order fulfillment time and fees action_link(s) in your feeds
  3. Instructions on how to update that availability and fees if it changes throughout the day
  4. Expectations for accuracy

For a full feed sample that shows usage of order fulfillment time as well as fees and minimum orders, see the Food Ordering EPA sample.

What order fulfillment time & fees information is required

Food ordering order fulfillment time for this experience is collected using google.protobuf.duration which allows the partners to specify a value using seconds and nanoseconds. Duration will be converted into minutes when it is being displayed to users with a message similar to "ETA 30 mins" or "ETA 15 mins".

Each day, when uploading a new Merchant feed, new order fulfillment time data should be included. Because the frontend only displays the current order fulfillment time, it is only necessary to provide the order fulfillment time information for a single day for any given location.

Specifying order fulfillment time through feeds

Order fulfillment time for action links is included in the Merchant feed action_link message, as part of the food_ordering_metadata field. For each action_link associated with the merchant, you are required to provide fulfillment information using one of the message paths.

Fixed Fulfillment Time

  • Merchant.action_link.food_ordering_metadata.fulfillment_lead_time_duration

This messages should be in the following format:

{
  "fulfillment_lead_time_duration": {
    "seconds" : 1800
  }
}

Range Fulfillment Time

  • Merchant.action_link.food_order_metadata.fulfillment_lead_time_duration_range

This message should be in the following format:

{
  "fulfillment_lead_time_duration_range": {
    "min_duration": {
       "seconds" : 1800
     },
    "max_duration": {
     "seconds" : 2400
    }
  }
}

Specifying fees through feeds

Similar to order fulfillment time, fees can be included as part of the action_link message under the food_ordering_metadata field. For each action_link associated with a merchant you can provide fee information using the message path:

merchant.action_link.food_ordering_metadata.fee_details

The message should be in the following format

{
  "type": "DELIVERY",
  "fee_amount": {
    "amount": {
      "currency_code": "USD",
      "units": 1,
      "nanos": 990000000
    }
  }
}

Updating order fulfillment time with real-time updates

If a location’s order fulfillment time for delivery or pickup changes between the times you send a daily feed, the real-time update REST API can be used to update the order fulfillment time that is shown to users.

Updates are done to a single merchant at a time. When making an update, you will specify the merchant to update, and the fields that should be updated as part of the API endpoint. Then in the body of the request you will include the new data for those fields. Any fields being updated will be replaced with the provided information.

To update the order fulfillment time you will make a patch request to the following endpoint:

PATCH https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/{merchantId}?updateMask=action_link

The body of the request would then be a Merchant object with just the action_link included (since we have set the updateMask to only include the action_link):

{
  "action_link": [
    {
     ..., // all required action_link fields here
     "food_ordering_metadata": {
       "fee_details": { … // Updated fee details here
         "type": "DELIVERY",
          "amount": {
            "currency_code": "USD",
            "units": 1,
            "nanos": 750000000
          }
       }
     }
    ... // remaining food ordering metadata information here
    }
  ]
}

If the API request is successful, the response will include the Merchant object with the newly updated data.

Order fulfillment time accuracy

Reserve with Google understands that the specifics of order fulfillment time change based on a variety of factors. These factors include:

  • Changes to order fulfillment time based on order size
  • Changes to order fulfillment time based on time to complete ordering and checkout
  • Latency between when order fulfillment time changes are updated, either through feeds or through real-time updates
  • The user's delivery address.

Any of these factors may lead to situations where the order fulfillment time displayed to the user initially is not the final fulfillment time they will see at checkout. The goal of the fulfillment time implementation is not to eliminate these entirely, but to provide clear information to users as often as possible.

Partners are expected to provide an implementation that leads to accurate fulfillment time displayed to users as often as is possible, on a best effort basis. Additionally, if fulfillment time does change due to order details, this should be clearly shown to users. If you are unsure of specifically what is required in your case, reach out to your Reserve with Google contact.