Implement the booking server

This guide covers three ways to implement the booking server:

• The standard implementation. This allows Reserve with Google to create appointments, bookings, and reservations with you on behalf of the user.
• The Order-based implementation. This is used when you participate in the order-based booking pilot program. This allows you to book multiple services at once within a single order.
• The waitlist implementation. This is used when you participate in the waitlist pilot program. This allows Reserve with Google to retrieve wait estimates and create waitlist entries on behalf of the user.

These three implementations share many of the same steps. Throughout this guide, we first discuss the standard implementation. When the steps differ for the Order or Waitlist implementations, we explain the differences.

Refer to the Partner Portal documentation to learn how to configure the connection to your Sandbox and Production booking servers.

Implement a REST API interface

Implement an API interface based on REST. This allows Google to send booking server requests over HTTP.

To start, set up a development or sandbox booking server that can be connected to the Reserve with Google sandbox environment. Only move to a production environment once the sandbox server is fully tested.

Methods

For each type of booking server, a different set of API methods are required on your end. Optionally, you can download the service definition in proto format to get started with the API implementation. The following tables show the methods for each implementation and include links to the service proto formats.

Standard implementation
Standard service definition. Download the proto service definition file.

Method	HTTP Request
HealthCheck	GET /v3/HealthCheck/
BatchAvailabilityLookup	POST /v3/BatchAvailabilityLookup/
CreateBooking	POST /v3/CreateBooking/
UpdateBooking	POST /v3/UpdateBooking/
GetBookingStatus	POST /v3/GetBookingStatus/
ListBookings	POST /v3/ListBookings/

Order implementation
Order service definition. Download the proto service definition file.

Method	HTTP Request
HealthCheck	GET /v3/HealthCheck/
CheckOrderFulfillability	POST /v3/CheckOrderFulfillability/*
CreateOrder	POST /v3/CreateOrder/*
ListOrders	POST /v3/ListOrders/*

Waitlist implementation
Waitlist service definition. Download the proto service definition file.

Method	HTTP Request
HealthCheck	GET /v3/HealthCheck/
BatchGetWaitEstimates	POST /v3/BatchGetWaitEstimates/
CreateWaitlistEntry	POST /v3/CreateWaitlistEntry/
GetWaitlistEntry	POST /v3/GetWaitlistEntry/
DeleteWaitlistEntry	POST /v3/DeleteWaitlistEntry/

API resources

The following resource types are used in the standard implementation:

• Slot: An inventory slot.
• Booking: An appointment for an inventory slot.

The following resources are used to implement order-based booking:

• TicketType: The types of tickets, which must be provided in the Services feed to enable orders of multiple tickets for a service slot.
• LineItem: A line item, which contains ordered tickets for a single service in a single time slot.
• Order: An order for a list of line items.

The following resources are used to implement waitlist-based booking:

• WaitEstimate: A wait estimate for a specific party size and merchant.
• WaitlistEntry: A user’s entry in the waitlist.

Flow: create a booking

This section covers how to create a booking for the standard implementation. To create multiple bookings in a single order with the Order implementation, see Flow: create an order. To create a waitlist with the Waitlist implementation, see Flow: create a waitlist entry.

Caution: Before you start work on your booking server, determine how you want to use it. You can't create orders or waitlists if you use the standard implementation.

Figure 1: Workflow to create a booking from a slot

When a user creates a booking, Google sends you the user's given name, surname, phone number, and email. From your point of view, this booking needs to be treated as a guest checkout, because Reserve with Google can't look up the user's account in your system. Make sure the final booking appears identical to your merchants' bookings that come from your booking system.

Flow: create an order

This section covers how to create a booking for the Order implementation. To create a waitlist with the Waitlist implementation, see Flow: create a waitlist entry.

Caution: Before you start work on your booking server, determine how you want to use it. You can't create waitlists if you use the Order implementation.

Figure 2: Workflow to create an order

When the user adds new items to their pending order, Google sends you CheckOrderFulfillability requests before the order is created. This checks whether the pending order can be fulfilled in its current state. Potential order fulfillability errors are defined in OrderFulfillability. You have the option to also send updated availability and price information in CheckOrderFulfillability responses.

When a user creates an order, Google sends you the user's given name, surname, phone number, and email. The email is the same as the user's Google account and is treated as a unique identifier. From your point of view, this order needs to be treated as a guest checkout, because Reserve with Google can't look up the user's account in your system. Make sure the final order appears identical to your merchants' orders that come from your booking system.

Flow: create a waitlist entry

This section covers how to create a booking for the Waitlist implementation. To create multiple bookings in a single order with the Order implementation, see Flow: create an order.

Caution: Before you start work on your booking server, determine how you want to use it. You can't create orders if you use the Waitlist implementation.

Figure 3: Workflow to create a waitlist entry

When the user creates a waitlist entry, Google sends you the user's given name, surname, phone number, and email. The email is the same as the user's Google account and is treated as a unique identifier. From your point of view, this waitlist needs to be treated as a guest checkout, because Reserve with Google can't look up the user's account in your system. Make sure the final waitlist entry appears identical to your merchants' entries that come from your waitlist system.

Security and Authentication

All communication to your booking server happens over HTTPS, so it's essential that your server has a valid TLS certificate that matches its DNS name. To help set up your server, we recommend the use of a freely available SSL/TLS verification tool, such as Qualys' SSL Server Test.

Booking server credentials can be entered in the Booking Server Configuration page within the Partner Portal. Passwords must be rotated every six months.

Sample Skeleton Implementations

To get started, check out the following sample skeletons of a booking server written for Node.js and Java frameworks:

• Node.js skeleton js-maps-booking-rest-server-v3-skeleton
• Java skeleton java-maps-booking-rest-server-v3-skeleton

These servers have stubbed out REST methods. They're required to implement the API v3 interface for booking- or order-based integrations. For a waitlist-based integration, change them to the required waitlist methods.

Requirements

HTTP errors and business logic errors

When your backend handles HTTP requests, two types of errors may occur. There can be unexpected errors from incorrect data, and from business logic errors.

Return any unexpected errors, if encountered, to the client with standard HTTP error codes. See the full HTTP status code list.

The types of business logic errors you can encounter are different for the different types of server implementations.

For the Standard implementation, the possible business logic errors are captured in Booking Failure, and they're returned in the HTTP response. Business logic errors may be encountered when a resource is created or updated. For instance, when you handle the methods CreateBooking or UpdatingBooking. Examples include, but aren't limited to, the following:

• SLOT_UNAVAILABLE is used if the requested slot is no longer available.
• PAYMENT_ERROR_CARD_TYPE_REJECTED is used if the provided credit card type is not accepted.

For the Order-based implementation, business logic errors are captured in Order Failure, and they're returned in the HTTP response. Business logic errors may be encountered when a resource is created. For instance, when you handle the CreateOrder method. Examples include, but aren't limited to, the following:

• ORDER_UNFULFILLABLE is used if the requested order is no longer fulfillable. For example, if the number of tickets requested for a slot exceeds the number of tickets that remain, or if the price of the requested service has changed.
• PAYMENT_ERROR_CARD_TYPE_REJECTED is used if the provided credit card type isn't accepted.

For the Waitlist implementation, business logic errors are captured in Waitlist Business Logic Failure, and they're returned in HTTP response. Business logic errors may be encountered when a resource is created, for instance when you handle the CreateWaitlistEntry method. Examples include, but are not limited to, the following:

• ABOVE_MAX_PARTY_SIZE is used when the requested waitlist entry is over the merchant’s maximum party size.
• MERCHANT_CLOSED is used when the waitlist isn't open because the merchant is already closed.

Idempotency

Communication over the network is not always reliable and Google may retry HTTP requests if no response is received. For this reason, all methods that mutate state must be idempotent:

• Standard: CreateBooking; UpdateBooking.
• Order: CreateOrder.
• Waitlist: CreateWaitlistEntry; DeleteWaitlistEntry.

For every request message except UpdateBooking and DeleteWaitlistEntry, idempotency tokens are included to uniquely identify the request. This allows you to distinguish between a retried REST call, with the intent to create a single request, and two separate requests. UpdateBooking and DeleteWaitlistEntry are uniquely identified by their booking and waitlist entry IDs respectively, so no idempotency token is included in their requests.

The following are some examples of how booking servers handle idempotency:

• A successful CreateBooking HTTP response includes the created booking. In some cases, payment is processed as part of the booking flow. If the exact same CreateBookingRequest is received a second time (with the same idempotency_token), then the same CreateBookingResponse must be returned. No second booking is created, and the user is charged exactly once, if applicable.

  Note that if a CreateBooking attempt fails and the same request is resent, your backend should retry it in this case.

• A successful CreateOrder HTTP response includes the created order. If the exact same CreateOrder request is received a second time (with the same idempotency_token), then the same CreateOrderResponse must be returned. No second order is created and the user is charged exactly once, if applicable.

  Note that if a CreateOrder attempt fails and the same request is resent, your backend should retry in this case.

• A successful CreateWaitlistEntry HTTP response includes the created waitlist entry ID. If the same CreateWaitlistEntryRequest is received a second time (with the same idempotency_token), then the same CreateWaitlistEntryResponse must be returned. No second waitlist entry is created and no error is returned.

  Note that if a CreateWaitlistEntry attempt fails and the same request is resent, your backend should retry in this case.

The idempotency requirement applies to all methods that mutate state.