# Reservations End-to-End Querying Merchant Status via the API

## Use cases


[Google Maps Booking API](https://developers.google.com/maps-booking/reference/maps-booking-api/rest) provides two methods, which can be used
to programmatically retrieve a status of the individual merchants for
various integrations or
[Local Services Ads](https://ads.google.com/local-services-ads)
inventory.

Use cases for Merchant Status API:

- Enhance existing customer relation management tools to demonstrate your customers how their inventory is surfaced on Google.
- Build a dashboard to track the inventory status and matching status of your merchants.
- Programmatically retrieve matching and bookable statuses of your merchants and fix any incorrect information to improve data quality.

## What does the merchant status contain

The
[MerchantStatus](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/MerchantStatus) contains the following information:

- Merchant inventory status: applies to both booking and/or waitlist merchants.
- Merchant matching status: includes details on the matched business listing
- For [Google Local Services Ads](https://ads.google.com/local-services-ads) only) Matched merchant service provider: includes the customer ID and service categories.
- The URLs to demonstrate how the merchant is surfaced on Google.

## Look up a single merchant status

You can get the status of a single merchant using
[inventory.partners.merchants.getStatus](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.merchants/getStatus):

```
GET https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/{merchantId}/status
```

Here is a Python code sample (see examples in more languages
[here](https://developers.google.com/actions-center/verticals/reservations/e2e/reference/real-time-updates-rest/code-samples)):

```
from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

credentials = service_account.Credentials.from_service_account_file(
    './your_key.json')
scoped_credentials = credentials.with_scopes(
    ['https://www.googleapis.com/auth/mapsbooking'])
authed_session = AuthorizedSession(scoped_credentials)

response = authed_session.get('https://partnerdev-mapsbooking.googleapis.com' +
    '/v1alpha/inventory/partners/123456789/merchants/001/status')
```

An example
[MerchantStatus](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/MerchantStatus) response looks like:

```
  {
    "name": "partners/123456789/merchants/001/status",
    "merchantName": "Foo Bar Restaurant",
    "inputGeoInfo": {
      "unstructured_address": "123 Foo Bar Street, Mountain View"
    },
    "processingStatus": "COMPLETED",
    "bookingStatus": {
      "hasValidFutureInventory": true
    },
    "waitlistStatus": {
      "hasValidWaitlistService": true
    }
    "geoMatch": {
      "name": "Foo Bar Restaurant",
      "formattedAddress": "123 Foo Bar St, Mountain View, CA 94043",
      "placeId": "ChIAAAAAAAAABBBBBBBB"
    },
    "directUrls": [
      {
        "type": "BOOKING",
        "url": "https://reserve-partnerdev.sandbox.google.com/maps/reserve/v/dine/m/Nwaaaaa"
      },
      {
        "type": "WAITLIST",
        "url": "https://reserve-partnerdev.sandbox.google.com/maps/reserve/v/wait/c/iDbbbbb"
      }
    ]
  }
```

## Retrieve merchant statuses in bulk

You can retrieve statuses of all merchants, or a group of merchants
satisfying certain inventory/matching conditions, using
[inventory.partners.merchants.status.list](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.merchants.status/list). For example, you can make
this call to get all unmatched merchants with valid future-dated booking
inventory:

```
GET https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/status?pageSize=50&bookingInventoryStatusRestrict=HAS_VALID_FUTURE_INVENTORY&geoMatchRestrict=GEO_UNMATCHED
```

A sample response would look like this:

```
  {
    "merchantStatuses": [
      {
        "name": "partners/123456789/merchants/002/status",
        "merchantName": "Bar Foo Restaurant",
        "inputGeoInfo": {
          "unstructured_address": "234 Bar Foo Street, Mountain View"
        },
        "processingStatus": "COMPLETED",
        "bookingStatus": {
          "hasValidFutureInventory": true
        },
        "waitlistStatus": {},
      },
      ...
      {
        "name": "partners/123456789/merchants/080/status",
        "merchantName": "Baz Restaurant",
        "inputGeoInfo": {
          "unstructured_address": "345 Baz Street, Mountain View"
        },
        "processingStatus": "COMPLETED",
        "bookingStatus": {
          "hasValidFutureInventory": true
        },
        "waitlistStatus": {
          "hasValidWaitlistService": true
        },
      },
    ],
    "nextPageToken": "AAABBBB"
  }
```

This response will contain 50
[MerchantStatus](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/MerchantStatus) that satisfy the filtering conditions and ordered by
`merchant_id`. The response also contains a page token (if it is
not the last page) to query the next page.

Please note: the filtering conditions should be consistent across all
pages.

## Best Practices

Since merchant statuses do not change frequently in most times, it is
encouraged to cache the retrieved results and periodically (e.g. every few
hours) retrieve them via new queries. The Actions Center may throttle your
queries if the number of requests per second deem to be excessively high.