This tutorial walks through:
- A high level description of how availability is shown to the user, and what type of data is required
- Specific instructions on how to encode the availability data into
the
action_link's in your feeds - Instructions on how to update that availability if it changes throughout the day
- Expectations for availability accuracy
Along with the availability metadata, it is also expected that you provide metadata about fees associated with delivery or pickup, as well as minimum order amounts. For a full feed sample that shows usage of Availability as well as fees and minimum orders, see the Retail Ordering v1 Feed Sample.
What availability information is required
Retail Ordering availability for this experience is collected at day-level granularity. This availability data is displayed to users along with fees & minimum order amounts with a message like “Available today”, “Available tomorrow” or “Available DD/MM” based on the earliest available date provided.
When submitting this data in the feeds, you will be sending future dates that have availability as well as the latest time that a user could place an order and schedule their pickup or delivery for each date. These two pieces of information are the fulfillment date and last ordering time respectively.
For example: If today’s date is March 23rd, 2021 and there is availability for delivery tomorrow as long as the user orders by today at 4:00PM, then the data you would provide to represent this availability is:
- Fulfillment date: 2021/03/24
- Last ordering time: 2021/03/23 4:00PM
Since the last ordering time is included, after that time has passed, the Google front-end will automatically update to the next available date, after the last ordering time has passed.
Each day, when uploading a new merchant feed, new availability data should be included. Because the front end only displays the current availability, it is only necessary to provide the next 3-5 availability dates for any given location. This allows the front end to display the current availability as well as have the next availability to display after the last ordering time has passed.
Specifying availability through feeds
Availability for action links is included in the Merchant feed
action_link message, as part of the
order_online_metadata field. For each merchant and each
fulfillment option, there is a list of
AvailableDay messages at the path
Merchant.action_link.order_online_metadata.fulfillment_option.available_day
These messages should be in the following format:
{
"fulfillment_date": {
"year": "2020",
"month": "10",
"day": "1"
},
"last_ordering_time": {
"seconds": "1601614800" // 2020/10/1, 10pm
}
}
In this format, the fulfillment_date is the year, month, and
day that has availability. This date should be in reference to the
location specified by this merchant.
The last_ordering_time is a unix timestamp in seconds. It is
timezone independent, and marks the last moment that the merchant can
take orders for the date provided in fulfillment_date. The last
ordering time can be any time earlier than, or during the fulfillment
date. Once the last ordering time has passed, Google will
automatically stop showing availability for the given fulfillment
date, and will start showing availability based on the next available
fulfillment date.
For the reference definition of order_online_metadata, see the
Merchant Feed Reference. For a feed sample that includes availability
in JSON format, see
Feed samples Retail Ordering + Metadata..
Updating availability with real-time updates
If a location’s availability 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 availability 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 availability 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
"order_online_metadata": {
"fulfillment_option": [
"fulfillment_type": "FULFILLMENT_TYPE_DELIVERY",
"available_day": [ // Include the updated availability here
{
"fulfillment_date": {
"year": "2020",
"month": "10",
"day": "1"
}
"last_ordering_time": {
"seconds": "1601614800" // 2020/10/1, 10pm
}
},
... // Other updated availability_days
]
]
}
]
}
If the API request is successful, the response will include the Merchant object with the newly updated data.
For a full reference specification of the Merchant update method, see: Method: inventory.partners.merchants.patch.
Availability accuracy
Reserve with Google understands that the specifics of availability change based on a variety of factors. These factors include:
- Changes to availability based on order size
- Changes to availability based on time to complete ordering and checkout
- Latency between when availability changes are updated, either through feeds or through real-time updates
Any of these factors may lead to situations where the availability displayed to the user initially is not the final availability they will see at checkout. The goal of the availability 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 availability displayed to users as often as is possible, on a best effort basis. Additionally, if availability 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.