Adding availability for Retail Ordering v1 integrations

Objective: Learn how to specify availability for pickup and delivery action links, and how to update that availability as it changes.

Note: This guide only applies to partners who are currently onboarding inventory through our Reserve with Google Starter Integration with Retail Ordering actions.

This tutorial walks through:

1. A high level description of how availability is shown to the user, and what type of data is required
2. Specific instructions on how to encode the availability data into the action_link's in your feeds
3. Instructions on how to update that availability if it changes throughout the day
4. 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.

Note: If a single merchant has multiple fulfillment options (pickup and delivery), the availability must be specified separately for each fulfillment option.

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.

Note: For detailed instructions on how to set up your integration to use the real-time updates, see our tutorial: Authenticating with Maps Booking API.

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.