## Use Cases for Real-Time Updates

Real-Time Updates must always be issued in the following scenarios:

- When a user cancels a reservation on your system, and the slot becomes available.
- When a user books a reservation through the Actions Center and the availability slot is no longer available.
- When a reservation made through the Actions Center is cancelled on your side, for example, by the merchant directly. You will need to update the booking as well as the availability because the original slot is now available again.


Additionally, if you implement
[Availability Replace RTU](https://developers.google.com/actions-center/verticals/reservations/e2e/integration-steps/real-time-api-updates#rtu-methods),
Real-Time Updates should be issued in the following scenarios:

- When a merchant changes their schedule (availability) on your system.
- When a user books a reservation on your system and the availability slot is no longer available.
- If you are using a legacy integration with [`CheckAvailability`](https://developers.google.com/actions-center/legacy/reference/booking-server/checkavailability-method), when a booking server [`CheckAvailability`](https://developers.google.com/actions-center/legacy/reference/booking-server/checkavailability-method) call returns inventory that does not match the actual inventory.

Not all Maps Booking API calls are required. The following are mandatory:

- [`notification.partners.bookings.patch`](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/notification.partners.bookings/patch) (`BookingNotification.UpdateBooking`)

Depending on the type of integration the following might also be available or required:

- [`inventory.partners.availability.replace`](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.availability/replace) (`InventoryUpdate.BatchServiceAvailability`) OR [`inventory.partners.merchants.services.availability.replace`](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.merchants.services.availability/replace) (`InventoryUpdate.ReplaceServiceAvailability`)

## Update Booking RTU

In the event that an update has been made to an Actions Center booking (e.g. canceled or
modified) on your system, a
[`notification.partners.bookings.patch`](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/notification.partners.bookings/patch)
(`BookingNotification.UpdateBooking`)
must be sent.

**Modifiable Fields**

- `status`
- `startTime`
- `duration`
- `partySize`
- `paymentInformation.prepaymentStatus`

> [!NOTE]
> **Note:** `name`, `merchant_id`, `service_id`, and the specific field that is changing must be specified. All other fields are optional. In some circumstances, multiple fields can change at the same time, in this case, comma separate the fields in the `updateMask` (e.g. `updateMask=partySize,startTime`).

**Cancellation example**

```
Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{
  "name": "partners/<PARTNER_ID>/bookings/<BOOKING_ID>",
  "merchantId": "10001",
  "serviceId": "1001",
  "startTime": "2025-01-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}
```

## Availability Replace RTU

> [!NOTE]
> **Note:** Availability Replace RTU is only availaible/required for some type of integration. If you are not sure, please confirm with your Google POC.

There are two types of replace methods available to update your
availability:

- [Batch Replace](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.availability/replace) (`InventoryUpdate.BatchServiceAvailability`): Completely replaces the availability data for multiple merchants and services.
  - *Note: This batch call does not guarantee atomicity. Only
    successfully updated availability slots will be returned.*
- [Single Replace](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.merchants.services.availability/replace) (`InventoryUpdate.ReplaceServiceAvailability`): Completely replaces the availability for a single merchant and service.

Please use the following
[reference](https://developers.google.com/maps-booking/reference/maps-booking-api/rest) for more
details.

Real-time updates **must** use the same availability structure as the data
that are sent through feeds. They must use one of:

- `spotsOpen`
- `recurrence`

### Choosing a Replace Method to Call

Use the following guide to help you determine which replace method is more
suitable:

- Are multiple merchants impacted? For example, replace availability for multiple merchants in one request.
  - [Batch Replace](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.availability/replace)
- Your system will synchronize with Google's from time to time by sending all availability changes since last update (not recommended).
  - [Batch Replace](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.availability/replace)
  - *Note: We expect the Inventory RTU to be sent within 5 minutes of an update occurring
    on your side. So you should check and send any updates at least every 5 minutes.*
- None of these apply or you only need to update a single merchant and service?
  - [Single Replace](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.merchants.services.availability/replace)
  - *Note: You can use multiple single replace calls to emulate a
    batch replace call, but it would be more efficient to use a single
    batch replace call*

### Real-Time Updates: Spots Open Format

It is important to use the same format across the feeds, booking server, and
real-time updates.

A `spots_open` feed snippet looks like:

**Feed Snippet**

```
   "availability": [
          {
            "merchant_id": "1001",
            "service_id": "12310",
            "spots_open": 2,
            "spots_total": 2,
            "start_sec": 1735831800, # January 02, 2025 15:30:00
            "duration_sec": 1800,
            "availabilityTag": "1000001"
          }
    ]
```

For the Inventory Update API, the replace request body format for when a
3:30 PM slot gets booked:

**Replace Real-Time Updates Snippet**

```
  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
        "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2025-01-02T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "spotsTotal": "2",
            "availabilityTag": "1000001"
          }
        ]
      }
    ]
  }
```

Here's an example of what we expect in the next daily feed, if a new slot at
3:30 PM gets booked:

**Feed Snippet**

```
"availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 2,
          "start_sec": 1735831800, # January 02, 2025 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]
```

> [!NOTE]
> **Note:** In the case there is no more availability left (`spots_open` is 0), there are 2 possible formats of sending the replace request for the Inventory API.
>
> - **Explicit specification:** This is the recommended method if you
>   have `spots_total > 1`
>
>   ```
>     {
>       "extendedServiceAvailability": [
>         {
>           "merchantId": "1001",
>           "serviceId": "12310",
>           "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
>           "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
>           "availability": [
>             {
>               "startTime": "2025-01-02T15:30:00.00Z",
>               "duration": "3600s",
>               "spotsOpen": "0",
>               "spotsTotal": "2",
>               "availabilityTag": "1000001"
>             }
>           ]
>         }
>       ]
>     }
>   ```
> - **Empty specification:** This is recommended only if `spots_total = 1`
>   for most merchants and services.
>
>   ```
>     {
>     "extendedServiceAvailability": [
>       {
>         "merchantId": "1001",
>         "serviceId": "12310",
>         "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
>         "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
>         "availability": [
>           {}
>         ]
>       }
>     ]
>   }
>   ```

### Real-Time Updates: Recurrence Format

It is important to use the same format across the feeds, booking server, and
real-time updates.

A feed that uses recurrence looks like:

**Feed Snippet**

```
  "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            }
          ],
        }
      ]
```

For the Inventory Update API, the replace request body format for when a
3:30 PM slot gets booked, looks like:

```
  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2018-10-30T15:01:23.045123456Z",
        "endTimeRestrict": "2018-10-30T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2018-10-30T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "scheduleException": [
             {
                "timeRange": {
                  "startTime": "2018-10-30T12:30:00.00Z",
                  "endTime": "2018-10-30T13:00:00.00Z"
                }
              },
              {
                "timeRange": {
                  "startTime": "2018-10-30T15:30:00.00Z",
                  "endTime": "2018-10-30T16:00:00.00Z"
                }
              }
            ]
          }
        ]
      }
    ]
  }
```

> [!NOTE]
> **Note:** Real-time updates should contain all `schedule_exceptions` for the slots that got booked. The reason for this is because [the API method](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.merchants.services.availability/replace) **replaces** the availability for that specific service and merchant. If you are replacing it with something else, it has to be **the complete information about that service's availability** , and include **all of its booked slots**.

Here's an example of what is expected in the next daily feed. Notice that it
is the entire service's availability for that merchant, and all of its
previous and new `schedule_exceptions`:

**Feed Snippet**

```
   "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            },
            {
              "time_range": {
                "begin_sec": 1540913400, # October 30, 2018 3:30:00 PM
                "end_sec": 1540915200 # October 30, 2018 4:00:00 PM
              }
            }
          ],
        }
      ]
```

### When to Submit Real-Time Updates

Real-time updates should be sent continuously whenever availability changes.
This is in addition to a comprehensive availability feed that should be
submitted once daily, in order to ensure that availability is synchronized
between your and Google's systems.