Package google.maps.booking.v1alpha

Index

BookingNotification

Receives notifications for appointments from external scheduling partners. The partner should call either UpdateBooking or UpdateOrder depending on whether the partner implements booking based RPCs such as CreateBooking and CheckAvailability, or order base RPCs such as CreateOrder and CheckOrderFulfillability.

UpdateBooking

rpc UpdateBooking(UpdateBookingRequest) returns (Booking)

Updates an existing Booking.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
UpdateOrder

rpc UpdateOrder(UpdateOrderRequest) returns (Order)

Updates an existing Order.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking

Feed

Retrieve processing status for uploaded feeds by external aggregator partners.

GetStatus

rpc GetStatus(GetStatusRequest) returns (FeedStatus)

Retrieves the Status of a previously uploaded feed by the specified aggregator, and returns it.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
ListStatus

rpc ListStatus(ListStatusRequest) returns (ListStatusResponse)

Retrieves the Status of multiple previously uploaded merchant, service, or availability feeds by the specified aggregator, and returns them.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking

InventoryUpdate

Receives inventory updates from external aggregators.

BatchReplaceServiceAvailability

rpc BatchReplaceServiceAvailability(BatchReplaceServiceAvailabilityRequest) returns (BatchReplaceServiceAvailabilityResponse)

Replaces the Availability of existing Services. This batch call does not guarantee atomicity. Only successfully updated availability slots will be returned.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
CreateMerchant

rpc CreateMerchant(CreateMerchantRequest) returns (Merchant)

Creates a new Merchant managed by the specified aggregator, and returns it.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
CreateService

rpc CreateService(CreateServiceRequest) returns (Service)

Creates a new Service of a merchant managed by the specified aggregator, and returns it.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
DeleteMerchant

rpc DeleteMerchant(DeleteMerchantRequest) returns (Empty)

Deletes an existing Merchant managed by the specified aggregator. All the merchant's services and availability will be disabled, too. If you re-add the merchant later, the same set of services and availability slots will appear.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
DeleteService

rpc DeleteService(DeleteServiceRequest) returns (Empty)

Deletes an existing Service of a merchant managed by the specified aggregator. All the service's availability will be deleted, too.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
ReplaceServiceAvailability

rpc ReplaceServiceAvailability(ReplaceServiceAvailabilityRequest) returns (ServiceAvailability)

Replaces the Availability of an existing Service of a merchant managed by the specified aggregator, and returns it.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
UpdateMerchant

rpc UpdateMerchant(UpdateMerchantRequest) returns (Merchant)

Updates an existing Merchant managed by the specified aggregator, and returns it.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking
UpdateService

rpc UpdateService(UpdateServiceRequest) returns (Service)

Updates an existing Service of a merchant managed by the specified aggregator, and returns it.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/mapsbooking

ActionPlatform

The platform that the action is performed on. Web application is the general fallback. It is recommended to have at least one ActionLink with ACTION_PLATFORM_WEB_APPLICATION. Links with Android and iOS as platform are only used on the respective system.

Enums
ACTION_PLATFORM_UNSPECIFIED The platform is unspecified.
ACTION_PLATFORM_WEB_APPLICATION The action platform is web in general.
ACTION_PLATFORM_MOBILE_WEB The action platform is web on mobile devices.
ACTION_PLATFORM_ANDROID The action platform is Android OS.
ACTION_PLATFORM_IOS The action platform is iOS.

Availability

An availability slot of the merchant's service, indicating time and number of spots.

Fields
start_time

Timestamp

Start time of the appointment slot.

duration

Duration

Duration of the appointment slot

spots_total

int64

Number of total spots and open spots of this availability. Examples:

  • Yoga class of 10 spots with 3 booked: availability {spots_total: 10, spots_open: 7 ...}
  • Chair massage session which is already fully booked: availability {spots_total: 1, spots_open: 0 ...}

Note: If sending requests using the availability compression format defined below, these two fields will be inferred.

  • A Recurrence implies spots_total=1 and spots_open=1.
  • A ScheduleException implies spots_total=1 and spots_open=0.

spots_open

int64

Number of open spots.

availability_tag

string

An optional opaque string to identify this availability slot. If set, it will be included in the requests that book/update/cancel appointments.

resources

Resources

Optional resources used to disambiguate this availability slot from others when different staff members, or rooms are part of the service.

E.g. the same Yoga class with two 2 instructors:

availability { resources { staff_id: "1" staff_name: "Amy" }
               spots_total: 10 spots_open: 7 }
availability { resources { staff_id: "2" staff_name: "John" }
               spots_total: 5 spots_open: 2 }

payment_option_id[]

string

A list of ids referencing the payment options which can be used to pay for this slot. The actual payment options are defined at the Merchant level, and can also be shared among multiple Merchants.

This field overrides any payment_option_ids specified in the service message. Similarly payment_option_ids specified here do NOT have to be present in the service message, though must be defined at the Merchant level.

recurrence

Recurrence

The recurrence information for the availability, representing more than one start time. A recurrence should contain appointments for one working day.

schedule_exception[]

ScheduleException

Times when this service cannot be scheduled. To limit the number of schedule_exception messages, consider joining adjacent exceptions.

deposit

Deposit

Optional deposit for this availability. Overrides the service deposit if one was specified.

no_show_fee

NoShowFee

Optional no show fee for this availability. Overrides the service no show fee if one was specified.

require_credit_card

RequireCreditCard

Indicates whether the user must provide a credit card in order to book this availability slot. If the value is not set, it is inherited from the service level if it's set there. (optional)

ticket_type_id[]

string

Indicates a list of supported ticket types for this availability slot. If unset, all ticket types in the parent service are available for this slot. Note that the values of this field must be defined in the parent service. Examples:

  • Service with four ticket types: TicketType {ticket_type_id: "adult_1" short_description: "Adult weekdays"} TicketType {ticket_type_id: "adult_2" short_description: "Adult weekends"} TicketType {ticket_type_id: "youth_1" short_description: "Youth weekdays"} TicketType {ticket_type_id: "youth_2" short_description: "Youth weekends"}

To represent the inventory during the weekdays: availability {ticket_type_id: "adult_1" ticket_type_id: "youth_1"...}. To represent the inventory during the holidays: availability {ticket_type_id: "adult_2" ticket_type_id: "youth_2"...}.

  • Service with three ticket types: TicketType {ticket_type_id: "adult" short_description: "Adult"} TicketType {ticket_type_id: "youth" short_description: "Youth"} TicketType {ticket_type_id: "senior" short_description: "Senior"}

To indicate that all three ticket types are available for this time slot, use either availability {ticket_type_id: "adult" ticket_type_id: "youth" ticket_type_id: "senior" ...} or `availability {...}' (do not set ticket_type_id in this slot).

(optional)

scheduling_rule_overrides

SchedulingRuleOverrides

Availability scheduling rules. If fields are populated, they will override any corresponding scheduling rules on the service-level SchedulingRules.

confirmation_mode

ConfirmationMode

The confirmation mode that will be used when booking this availability. Attempts to create bookings for availabilities with a confirmation mode of CONFIRMATION_MODE_SYNCHRONOUS must be immediatlely confirmed or denied. Attempts to create bookings for availabilities with confirmation mode of CONFIRMATION_MODE_ASYNCHRONOUS must be either immediately denied or created with status PENDING.

ConfirmationMode

The confirmation modes used when booking availabilities.

Enums
CONFIRMATION_MODE_UNSPECIFIED The confirmation mode was not specified. Synchronous confirmation will be assumed.
CONFIRMATION_MODE_SYNCHRONOUS Bookings for this availability will be confirmed synchronously.
CONFIRMATION_MODE_ASYNCHRONOUS Bookings for this availability will be confirmed asynchronously.

Recurrence

Recurrence messages are optional, but allow for a more compact representation of consistently repeating availability slots. They typically represent a day's working schedule. ScheduleException messages are then used to represent booked/unavailable time ranges within the work day.

Requirements:

  1. The expansion of availability slots or recurrences must NOT create identical slots. If the ids, start_time, duration, and resources match, slots are considered identical.
  2. Do NOT mix the standard availability format and recurrence within the slots of a single service. Recurrence benefits merchants/services that offer appointments. The standard format is geared towards merchants/services with regularly scheduled classes.
  3. Recurrences should not last for more than 24 hours.
Fields
repeat_until

Timestamp

The inclusive maximum UTC timestamp the availability repeats until.

repeat_every

Duration

Defines the time between successive availability slots.

Example: An availability with a duration of 20 min, a repeat_every of 30 min, a start_time of 9:00am, and a repeat_until of 11:00am will yield slots at 9-9:20am, 9:30-9:50am, 10-10:20am, 10:30-10:50am, 11-11:20am. (required)

ScheduleException

ScheduleException messages represent booked/unavailable time ranges within the workday, which are exceptions to the recurrence described above. As time slots are booked, the list of exceptions should be updated to reflect the newly unavailable time ranges. The recurrence itself shouldn't be modified.

Fields
time_range

TimeRange

The time range of the exception. Any slots described by the recurrence which overlap this closed-open time range will be considered unavailable.

Example: If the recurrence specifies a duration of 20 min, a repeat_every of 30 min, a start_time of 9:00am, and a repeat_until of 11:00am, then a ScheduleException with a time_range of 9:45am-11:00am would make unavailable the slots at 9:30-9:50am, 10-10:20am, and 10:30-10:50am.

Note that because the time range is closed-open, the slot beginning at 11am slot would not be impacted.

SchedulingRuleOverrides

Availability level scheduling rules.

Fields
last_bookable_sec

int64

The last time (in seconds) that this slot is able to be booked. This timestamp must be before the start_sec of the slot to be respected (if users should be able to book after the start time, use service level SchedulingRules.min_booking_before_end_time). If present, will override anything specified in the min_booking_buffer of the corresponding Service's SchedulingRules.

first_bookable_sec

int64

The first time (in seconds) that this slot is able to be booked. This timestamp must be before the start_sec of the slot, or last_bookable_sec if specified.

BatchReplaceServiceAvailabilityRequest

The batch request to replace multiple Service's availability slots.

Fields
parent

string

Format of partners/{partner_id}.

extended_service_availability[]

ExtendedServiceAvailability

The extended service availability that is used to replace the existing availability slots.

BatchReplaceServiceAvailabilityResponse

The batch response to replace multiple Service's availability slots. Only successfully updated slots will be included in this message

Fields
extended_service_availability[]

ExtendedServiceAvailability

The successfully updated extended service availability messages that were used to replace the existing availability slots.

Booking

A booking for an inventory slot

Fields
name

string

Resource name of the booking: partners/{partner ID}/bookings/{booking ID}

merchant_id

string

ID of the merchant for the slot

service_id

string

ID of the merchant service

start_time

Timestamp

Start time of the appointment slot

duration

Duration

Duration of the appointment slot

client_information

ClientInformation

Personal information of the client making the appointment

status

BookingStatus

Status of the booking

payment_information

PaymentInformation

Information about payment transactions that relate to the booking.

party_size

int64

Party size of the booking

BookingFailure

Status data that conveys why processing of a booking failed asynchronously. BookingFailure is intended to primarily capture business logic errors.

Fields
cause

Cause

The reason why the booking failed. (required)

rejected_card_type

CreditCardType

(required only if cause is PAYMENT_ERROR_CARD_TYPE_REJECTED)

description

string

This optional field is used for the partner to include additional information for debugging purpose only. (optional)

payment_failure

PaymentFailureInformation

Information about payment failures.

Cause

Enumeration of failure causes.

Enums
CAUSE_UNSPECIFIED Default value: Don't use; amounts to an "unknown error"
SLOT_UNAVAILABLE The referenced availability slot is not available any longer.
SLOT_ALREADY_BOOKED_BY_USER The user has already booked an appointment for the referenced availability slot.
LEASE_EXPIRED The lease (if provided) has expired and cannot be used any longer to complete the requested booking.
OUTSIDE_CANCELLATION_WINDOW The requested cancellation cannot be performed at the current time due to time restrictions in the merchant's cancellation policy.
PAYMENT_ERROR_CARD_TYPE_REJECTED An error was encountered while processing the payment because the provided credit card type was not accepted by the merchant. The credit card type must be supplied in rejected_card_type.
PAYMENT_ERROR_CARD_DECLINED An error was encountered while processing the payment because the provided credit card was declined.
PAYMENT_OPTION_NOT_VALID An error was encountered with the pack/membership used to pay for the booking. There could be no valid uses left, it could have expired, etc.
PAYMENT_ERROR An error was encountered while processing the payment for this booking. Use this value to indicate a general payment related error, only if the error does not match to a specific payment error above.
USER_CANNOT_USE_PAYMENT_OPTION User cannot use the given payment option (e.g. user trying to use a first time price for the second time).
BOOKING_ALREADY_CANCELLED A booking that the user tried to cancel has already been cancelled.
BOOKING_NOT_CANCELLABLE A booking that the user tried to cancel is not cancellable.
OVERLAPPING_RESERVATION User has an existing reservation too close to this time.
USER_OVER_BOOKING_LIMIT Booking failed due to the user being over the aggregator's per-user bookings limit.
PAYMENT_REQUIRES_3DS1

Set when payment is rejected because you are requesting that the transaction be tried again, but this time after undergoing 3DS1 challenge/response. Note that the current transaction's failure state will stay failed. The retry will be completely separate.

When this is the failure reason, payment_failure.3DS1_parameters MUST be set. If it is not, then the current cause will be treated as if it were PAYMENT_ERROR.

PaymentFailureInformation

Information about payment failures.

Fields
threeds1_parameters

ThreeDS1Parameters

Parameters used by a RwG aggregator to initiate a 3DS1 authentication protocol with the user. Will be ignored unless BookingFailure.cause is set to PAYMENT_REQUIRES_3DS1.

ThreeDS1Parameters

Parameters requesting that RwG perform a 3DS1 challenge.

The parameters are set by EMVCo's description of the 3DS1 protocol.

Fields
acs_url

string

The URL from which to load a form to present to the User for authentication.

pa_req

string

A PaymentAuthentication Request. To be posted to the ACSUrl form.

transaction_id

string

An identifier used by the ACS provider. To be posted to the ACSUrl form.

BookingStatus

Status of a booking

Enums
BOOKING_STATUS_UNSPECIFIED Not specified.
CONFIRMED Booking has been confirmed
PENDING_MERCHANT_CONFIRMATION Booking is awaiting confirmation by the merchant before it can transition into CONFIRMED status (this is NOT currently supported)
PENDING_CLIENT_CONFIRMATION Booking is awaiting confirmation by the client before it can transition into CONFIRMED status (this is NOT currently supported)
CANCELED Booking has been canceled on behalf of the user.
NO_SHOW Client did not show for the appointment
NO_SHOW_PENALIZED Client did not show for the appointment in violation of the cancellation policy.
FAILED Booking could not be completed due to a processing failure.
DECLINED_BY_MERCHANT Booking was asynchronously declined by the merchant.

CancellationPolicy

Cancellation policy for a service.

Fields
refund_condition[]

RefundCondition

Zero or more refund conditions applicable to the policy.

RefundCondition

Defines a single refund condition. Multiple refund conditions could be used together to describe "refund steps" as various durations before the service start time.

Fields
min_duration_before_start_time

Duration

Duration before the start time, until when the customer can receive a refund for part of the service's cost specified in refund_percent. When set to 0 (default), the service can be cancelled at any time.

refund_percent

uint32

The percent that can be refunded, as long as the service booking is cancelled at least min_duration_before_start_time before the service start time, in the range of [0, 100]. When set to 0 (default), the service is not refundable. When set to 100 this service is fully refundable.

ClientInformation

Personal information about the person making a booking

Fields
given_name

string

Given name of the client

family_name

string

Family name of the client

address

PostalAddress

Address of the client

telephone

string

Phone number of the client

email

string

Email address of the client

CreateMerchantRequest

The request to create a Merchant.

Fields
parent

string

The parent resource name for the partner who owns this merchant, in the format of partners/{partner_id}.

merchant_id

string

The merchant id to use for this merchant.

merchant

Merchant

The merchant to create.

CreateServiceRequest

The request to create a new Service.

Fields
parent

string

The parent resource name for the merchant who owns this service, in the format of partners/{partner_id}/merchants/{merchant_id}.

service_id

string

The service id to use for this service.

service

Service

The service to create.

CreditCardRestrictions

Restrictions to the credit card types this merchant accepts.

Fields
credit_card_type[]

CreditCardType

A list of supported credit cards. No credit cards are supported if empty.

CreditCardType

A credit card type.

Enums
CREDIT_CARD_TYPE_UNSPECIFIED Unused.
VISA A Visa credit card.
MASTERCARD A Mastercard credit card.
AMERICAN_EXPRESS An American Express credit card.
DISCOVER A Discover credit card.
JCB A JCB credit card.

DeleteMerchantRequest

The request to delete a Merchant.

Fields
name

string

The resource name of the merchant to delete. In the format of partners/{partner_id}/merchants/{merchant_id}

DeleteServiceRequest

The request to delete a Service.

Fields
name

string

The resource name of the service to delete. In the format of partners/{partner_id}/merchants/{merchant_id}/services/{service_id}

Deposit

A deposit that the user may be charged or have a hold on their credit card for.

Fields
deposit

Price

Deposit amount.

min_advance_cancellation_sec

int64

Minimum advance cancellation for the deposit.

deposit_type

PriceType

Defines how the deposit is determined from the availability.

ExtendedServiceAvailability

A list of availability and who/when they should be applied to.

Fields
merchant_id

string

This is a mandatory field required to specify which merchant the availability messages below belong to.

service_id

string

This is a mandatory field required to specify which service the availability messages below belong to.

start_time_restrict

Timestamp

If provided, we will consider the Availability entities provided to be a complete snapshot from [start_time_restrict, end_time_restrict). That is, all existing availability will be deleted if the following condition holds true:

   start_time_restrict <= availability.start_sec &&
   availability.start_sec < end_time_restrict

If a duration message is set, the condition is futher restricted:

  availability.duration == duration_restrict

If a resources_restrict message is set, the condition is further restricted:

   availability.resources.staff_id == resources_restrict.staff_id &&
   availability.resources.room_id == resources_restrict.room_id

These fields are typically used to provide a complete update of availability in a given time range.

Setting start_time_restrict while leaving end_time_restrict unset is interpreted to mean all time beginning at start_time_restrict.

end_time_restrict

Timestamp

Setting end_time_restrict while leaving start_time_restrict unset is interpreted to mean all time up to the end_time_restrict.

duration_restrict

Duration

Setting duration further restricts the scope of the update to just the availability with matching duration.

resources_restrict

Resources

Setting resources_restrict further restricts the scope of the update to just this set of resources. All id fields of the resources must match exactly.

availability[]

Availability

The new list of availability.

FeedStatistics

Statistics obtained while processing an uploaded feed.

Fields
new_items

int64

Newly added items by this feed. Items can be merchants, services or availability slots, depending on the type of the feed.

existing_items

int64

Existing items, updated as needed from newer information from the feed.

deleted_items

int64

Items no longer present in this feed, and that were removed as a result.

FeedStatus

Status of a feed uploaded by the aggregator's platform.

Fields
name

string

The feed resource name, which has the format of

  • partners/{partner_id}/feeds/merchants/{file_name}
  • partners/{partner_id}/feeds/services/{file_name}
  • partners/{partner_id}/feeds/availability/{file_name}

state

State

The processing state of this feed.

error_details

string

Human readable string providing more details if we failed to process this feed.

statistics

FeedStatistics

Statistics specific to this feed.

State

Enum to indicate the processing state of a feed.

Enums
STATE_UNSPECIFIED Default value. Unused.
IN_PROGRESS The feed is still being processed.
SUCCESS The feed has been successfully processed.
FAILURE We encountered an error while processing the feed.

GeoCoordinates

The Geo data of a location, including latitude, longitude, and address.

Fields
latitude

double

Latitude in degrees. (optional)

longitude

double

Longitude in degrees. (optional)

Union field addresses. Address for a location, could either be structured or unstructured. addresses can be only one of the following:
address

PostalAddress

Postal address of the location, preferred.

unstructured_address

string

An unstructured address could also be provided as a fallback. E.g. "1600 amphitheatre parkway mountain view, ca 94043"

GetStatusRequest

The request to retrieve the Status for a specific feed uploaded by the aggregator's platform.

Fields
name

string

The feed resource name, which has the format of

  • partners/{partner_id}/feeds/merchants/{file_name}
  • partners/{partner_id}/feeds/services/{file_name}
  • partners/{partner_id}/feeds/availability/{file_name}

IntegrationType

Depth of integration supported.

Enums
INTEGRATION_TYPE_UNSPECIFIED Defaults to END_TO_END.
INTEGRATION_TYPE_END_TO_END Complete integration that allows end to end booking through Google.
INTEGRATION_TYPE_INVENTORY_ONLY Booking server doesn’t need to support this service. Only merchants, services, and (optionally) availability data need to be sent.

LineItem

A single item in an order--the booking of a single service in a single time slot.

Fields
service_id

string

ID of the merchant Service.

start_sec

int64

Start time of the appointment slot in seconds of UTC time since Unix epoch.

duration_sec

int64

Duration of the appointment slot in seconds.

tickets[]

OrderedTickets

Number of tickets ordered by Ticket Type.

price

Price

The total price (excluding taxes) of this Line Item.

status

BookingStatus

Status of the Line Item.

OrderedTickets

Number of ordered tickets by Ticket Type.

Fields
ticket_id

string

ID of a Ticket Type.

count

int32

Number of tickets ordered for this type.

ListStatusRequest

The request to retrieve the Status for multiple feeds uploaded by the aggregator's platform.

Fields
name

string

The feed resource name, which has the format of

  • partners/{partner_id}/feeds/merchants
  • partners/{partner_id}/feeds/services
  • partners/{partner_id}/feeds/availability

page_size

int32

The maximum number of items to return.

page_token

string

The next_page_token value returned from a previous List request, if any.

state_restrict

State

Optional restrict to filter results by feed state.

time_range_restrict

TimeRange

Optional restict to filter results by upper and lower bound. If start_time is unset, it will default to beginning of unix time. If end_time is unset, it will default to now.

ListStatusResponse

The request to retrieve the Status for multiple feeds uploaded by the aggregator's platform.

Fields
status[]

FeedStatus

Reverse chronological list of statuses for uploaded feeds. The maximum number of items returned is based on the page_size field in the request.

next_page_token

string

Token to retrieve the next page of results. There are no more results in the list if empty.

LocalizedString

Instance of a string in one locale.

Fields
locale

string

IETF BCP 47 language code, such as "en", "mas", "zh-Hant", "de-CH-1901". See http://www.w3.org/International/articles/language-tags/.

value

string

Message in the locale above (UTF-8).

Location

Geographic information about a location.

Fields
place_id

string

The Place ID for a place in the Google Places database and on Google Maps. See https://developers.google.com/places/place-id for more about Place IDs. If this is provided, Google will match the location to this place.

name

string

The location's name, telephone, url and geo are used to support matching the location with places already present on Google Maps. It is recommended to provide the location name if possible. (optional)

The name of the location. (optional)

telephone

string

The public telephone number of the location including its country and area codes, e.g. +14567891234. (optional)

url

string

The url of the location's public website. (optional)

geo

GeoCoordinates

The Geo info of the location, including latitude, longitude, and address. (optional)

location_type

LocationType

The type of the location, must be supplied if this location is provided for a Service.

location_id

string

Unique reference of the location within the service. This id can be used to refer to this location in other service fields. E.g in the custom intake form, a set of location ids can be used to specify pick up location options. If set, this id should be unique within the same service. (optional)

LocationType

The type of this location.

Enums
LOCATION_TYPE_UNSPECIFIED Location type unspecified.
VISITED_LOCATION The location where this service visits.
START_LOCATION The location where this service starts, also serves as MEETING_LOCATION.
END_LOCATION The location where this service ends.

Merchant

Info about a merchant that is on the aggregator's platform.

Fields
name

string

The merchant resource name, which has the format of partners/{partner_id}/merchants/{merchant_id}.

merchant_name

string

The merchant_name, telephone, url and geo are used to support matching partner inventory with merchants already present on Google Maps. This information will not be displayed.

The name of the merchant.

telephone

string

The public telephone number of the merchant including its country and area codes, e.g. +14567891234.

url

string

The url of the merchant's public website.

geo

GeoCoordinates

The Geo info of the merchant, including latitude, longitude, and address.

category

string

The category of the business in aggregator's platform.

num_bookings_30d
(deprecated)

int64

This field is deprecated.

tax_rate_basis_points
(deprecated)

uint32

The merchant's tax rate in basis points (one hundredth of one percent). For example, if the tax rate is 7.5%, this field should be set to 750.

If this field is left unset or set to 0, the total price charged to a user for any service provided by this merchant is the exact price specified by Service.price. The service price is assumed to be exempt from or already inclusive of applicable taxes. Taxes will not be shown to the user as a separate line item.

If this field is set to any nonzero value, the total price charged to a user for any service provided by this merchant will include the service price plus the tax assessed using the tax rate provided here. Fractions of the smallest currency unit (for example, fractions of one cent) will be rounded using nearest even rounding. Taxes will be shown to the user as a separate line item.

This field is deprecated, please use tax_rate instead.

tax_rate

TaxRate

The merchant's tax rate. If present this field overrides the deprecated tax_rate_basis_points field. An empty message (i.e. tax_rate { }) will reset the applied tax rate to zero.

payment_restrictions

PaymentRestrictions

Restrictions to the payment methods this merchant accepts. We assume no restrictions exist if this field is not set.

payment_option[]

PaymentOption

Payment options available for this merchant. Services under this merchant will be able to individually limit the payment options they allow.

payment_processor_config
(deprecated)

PaymentProcessorConfig

Configuration for a tokenized payment processor, if the merchant has support for it.

tokenization_config

TokenizationConfig

Configuration for a tokenized payment processor, if the merchant has support for it.

terms

Terms

The specific merchant's Terms and Conditions displayed to the user when a service is being booked through Reserve with Google. In addition to these the aggregator partner's Terms and Conditions are always displayed to the user and must not be provided here.

brand_id

string

An opaque string that identifies the consumer-facing brand to use when displaying partner attribution. This field allows partners with multiple consumer-facing brands to provide merchants for all brands within the same feed.

A brand consists of consumer-facing properties like the name, logo, Terms of Service, and Privacy Policy.

If there is only one consumer-facing partner brand, this field does not need to be set and can be ignored.

If the partner...

Does not have multiple consumer-facing brands? --> Ignore this field

Has Multiple Brands that are configured?

  If this field is set
    --> Associated consumer-facing brand attribution is used

  If this field is unset or the empty string
    --> Default consumer-facing brand attribution is used

Careful Note: most partners do not need to set this field. If a partner wishes to use this field, they must contact us first to configure separate brands, including the default brand.

matching_hints

MerchantMatchingHints

Hints to help Google match a merchant to a place on Google Maps. Note: most partners do not need to set this field, as Google will match merchants to places on Google Maps using the information provided above. (optional)

service_attribute[]

ServiceAttribute

Definitions for any service attributes used to describe the Services for this Merchant. (optional)

MerchantMatchingHints

Hints used to help Google match a merchant to a place on Google Maps.

Fields
place_id

string

The Place ID for a place in the Google Places database and on Google Maps. See https://developers.google.com/places/place-id for more about Place IDs.

NoShowFee

A fee that a user may be charged if they have made a booking but do not show up.

Fields
fee

Price

The amount the user may be charged if they do not show up for their reservation.

fee_type

PriceType

Defines how the fee is determined from the availability.

Order

An order for service appointments with a merchant.

Fields
name

string

Resource name of the order: partners/{partner ID}/orders/{order ID}

client_information

ClientInformation

Personal information of the client making the order.

payment_information

PaymentInformation

Information about payment transactions that relate to the order.

merchant_id

string

ID of the merchant that all services in this order belong to.

item[]

LineItem

Line items in this order.

PaymentInformation

Payment details that relate to a booking

Fields
prepayment_status

PrepaymentStatus

Prepayment status of the booking. If the prepayment_status is PREPAYMENT_PROVIDED or PREPAYMENT_REFUNDED, then payment_transaction_id contains the associated unique transaction id.

payment_transaction_id

string

Unique identifier for a payment transaction associated with the booking. Empty if not applicable.

PaymentOption

A payment option, which can be used to pay for services provided by a merchant. Payment options can be shared among multiple merchants (e.g. merchants belonging to the same chain).

Fields
payment_option_id

string

This ID is used to identify this payment option.

This ID is global to the whole aggregator, and re-using a value across multiple merchants will allow a user to pay with the corresponding payment option across those merchants.

When re-using an ID accoss multiple merchants, updating any value for a payment option under one merchant will also update any other payment option with the same ID, under a different merchant. As such, it's a best practice to have all payment options sharing the same ID, always be updated to identical values, to avoid any possibility of underministic behavior.

name

string

The name of the payment option. This can be user visible.

description

string

A description of the payment option. This can be user visible.

price

Price

The price of the payment option.

tax_rate

TaxRate

The tax rate for this payment option. If present this field overrides the tax_rate field present in the Merchant or Service. An empty message (i.e. tax_rate { }) will reset the applied tax rate to zero.

payment_option_type

PaymentOptionType

The type of this payment option. Single-use for drop-ins, multi-use for packs, and unlimited for memberships.

session_count

int64

How many sessions this payment option can be used for. Valid only for multi-session / packs, where the value should be > 1.

purchase_interval

TimeRange

The payment option can be purchased within this interval.

valid_interval

TimeRange

The payment option can be used within this interval (e.g. special price for January 2017). If present, this overrides valid_duration and activation_type.

valid_duration

Duration

Duration of the payment option validity (e.g. 30 day membership).

activation_type

ActivationType

Defines how the validity start date is determined for this payment option.

user_restriction

UserPurchaseRestriction

Restricts the users eligible to purchase this payment option. Can be used to restrict a promotional payment option to a subset of users. If not set, all users are eligible.

ActivationType

Defines how the validity start date is determined.

Enums
ACTIVATION_TYPE_UNSPECIFIED Unused.
ACTIVATION_ON_PURCHASE Validity starts at the time of purchase.
ACTIVATION_ON_FIRST_USE Validity starts when the payment option is used for the first time.

PaymentOptionType

A payment option type.

Enums
PAYMENT_OPTION_TYPE_UNSPECIFIED Unused.
PAYMENT_OPTION_SINGLE_USE Payment option can only be used once.
PAYMENT_OPTION_MULTI_USE Payment option can be used if its session count > 0.
PAYMENT_OPTION_UNLIMITED Payment option can be used within its valid time range - session count is inapplicable.

PaymentProcessorConfig

A configuration for a payment processor, setup on a per Merchant basis.

Fields
processor

Processor

Defines the payment processor partner this configuration applies to.

public_key

string

The key used to identify this merchant with the payment processor.

For Stripe, refer to: https://stripe.com/docs/dashboard#api-keys For Braintree, refer to: https://articles.braintreepayments.com/control-panel/important-gateway-credentials

version

string

The API version number sent to the payment processor along with payment requests.

Processor

Defines a specific payment processor partner.

Enums
PROCESSOR_UNSPECIFIED Unused
PROCESSOR_STRIPE A configuration for payments with Stripe.
PROCESSOR_BRAINTREE A configuration for payments with Braintree.

PaymentRestrictions

Restrictions to the payment methods this merchant accepts.

Fields
credit_card_restrictions

CreditCardRestrictions

Restrictions to the credit cards this merchant accepts. We assume all credit cards are accepted if this field is not set. Note that the list of cards supported by CreditCardType will grow over time, meaning that leaving this empty subjects a configuration to future changes.

PerOrderFee

Fees that must be paid once per order, regardless of number of tickets.

Fields
delivery_fee

Price

A fee that can vary by delivery method.

processing_fee

Price

A fee to process the user's payment method.

PerTicketFee

Fees that must be paid for each ticket the user purchases.

Fields
service_charge

Price

An extra charge assessed for a service.

facility_fee

Price

A fee that goes to the venue/facility.

taxes

Price

Per ticket taxes.

PostalAddress

Address of a customer or a business.

Fields
address_country

string

The country, specified using its ISO 3166-1 alpha-2 country code, e.g. "US" (required)

address_locality

string

The locality, e.g. "Mountain View". (required)

address_region

string

The region, e.g. "CA". This field is only required in countries where region is commonly a part of the address. (optional)

postal_code

string

The postal code, e.g. "94043". (required)

street_address

string

The street address, e.g. "1600 Amphitheatre Pkwy". (required)

PrepaymentStatus

Prepayment status of a booking.

Enums
PREPAYMENT_STATUS_UNSPECIFIED Not specified, defaults to PREPAYMENT_NOT_PROVIDED.
PREPAYMENT_PROVIDED The fee for the booking has been paid in advance.
PREPAYMENT_NOT_PROVIDED The fee for the booking has not been paid in advance.
PREPAYMENT_REFUNDED The fee was previously PREPAYMENT_PROVIDED but has now been refunded.

Price

The price of a service or a fee.

Fields
price_micros

int64

The price in micro-units of the currency. Fractions of smallest currency unit will be rounded using nearest even rounding. (e.g. For USD 2.5 cents rounded to 2 cents, 3.5 cents rounded to 4 cents, 0.5 cents rounded to 0 cents, 2.51 cents rounded to 3 cents).

currency_code

string

The currency of the price that is defined in ISO 4217.

pricing_option_tag

string

An optional and opaque string that identifies the pricing option that is associated with the extended price.

PriceInterpretation

Describes how a Price should be interpreted and displayed to the user.

Enums
PRICE_INTERPRETATION_UNSPECIFIED Price interpretation unspecified, defaults to EXACT_AMOUNT.
EXACT_AMOUNT

When the price should be interpreted as a specific value.

Examples: $20 for a yoga class; $15 for a child haircut

STARTS_AT

When the price of a service is variable but a minimum price is known and displayed to consumers. Consumers may make choices which increase the price.

Note that any service that uses this PriceInterpretation must use PrepaymentType NOT_SUPPORTED.

Examples: $30 for dog grooming, but additional consumer choices may increase the price

NOT_DISPLAYED

When the price of a service is variable and no price information is displayed to consumers ahead of time.

Note that any service that uses this PriceInterpretation must use PrepaymentType NOT_SUPPORTED and Price must be empty.

Examples: A consultation for a home service

PriceType

Defines how a total price is determined from an availability.

Enums
FIXED_RATE_DEFAULT

The price is for a fixed amount. This is the default value if the field is not set.

Examples: $50 deposit to reserve a table; $20 no show fee for a yoga class

PER_PERSON

The price specified is per person, and the total price is calculated according to the party size specified in Resources as price_micros * party_size. A PER_PERSON price must be accompanied by a party size in the availability resources. If it is not, a party size of one is used.

Examples: $10 each for tickets to a museum

Rating

Defines Rating for an entity.

Fields
value

double

Average rating value (required when number_of_ratings > 0). The value must be in the range of [1, 5] and can be omitted if and only if the number_of_ratings is zero.

number_of_ratings

uint64

Number of ratings used in calculating the value (required).

RelatedMedia

Photos related to this service. Google will crawl these media to ensure that they are displayed correctly to end-users. (optional)

Fields
url

string

URL of this media source. Google will crawl the media hosted at this URL.

type

MediaType

Type of this media source.

localized_caption

Text

Caption of the media that supports i18n, only plain text is supported. Any HTML components will be stripped. (optional)

attribution

Attribution

Attribution information about the source of the media. Note that if the attribution is required to display with the media to give credit to photographer or agency, this field must be set. (optional)

caption
(deprecated)

string

Deprecated, prefer to use localized_caption.

Attribution

Attribution information for this media.

Fields
localized_text

Text

The text to give credit to the photographer or agency supporting i18n. This text will be displayed together with the source media. Note that only plain text is supported for this field, any HTML components will be stripped (hyperlink based attribution is not supported).

text
(deprecated)

string

Deprecated, prefer to use localized_text.

MediaType

Enum to indicate the type of this media source. Only photos are supported. Please reach out to the Reserve with Google team if other media beyond photos need to be supported.

Enums
TYPE_UNSPECIFIED Unused.
PHOTO Indicates the media provided by the url is a photo.

ReplaceServiceAvailabilityRequest

The request to replace a Service's availability.

Fields
service_availability

ServiceAvailability

The service availability that is used to replace the existing ones.

RequireCreditCard

Defines whether a credit card is required in order to book an appointment.

Enums
REQUIRE_CREDIT_CARD_UNSPECIFIED The credit card requirement is not explicitly specified and the behaviour is identical to the one specified for CONDITIONAL.
REQUIRE_CREDIT_CARD_CONDITIONAL Google will require a credit card for the booking if any of the following conditions are met: * the availability has a price and the prepayment_type is REQUIRED * the no_show_fee is set * the deposit field is set.
REQUIRE_CREDIT_CARD_ALWAYS A credit card is always required in order to book this availability regardless of other field values.

Resources

A resource is used to disambiguate availability slots from one another when different staff members, or rooms are part of the service. Multiple slots for the same service and time interval can co-exist when they have different resources.

Fields
staff_id

string

Optional ID for a staff member providing the service. This field identifies the staff member across all merchants, services, and availability records. It also needs to be stable over time to allow correlation with past bookings. This field must be present if staff_name is present.

staff_name

string

Optional name of a staff member providing the service. This field will be displayed to users making a booking, and should be human readable, as opposed to an opaque identifier. This field must be present if staff_id is present.

room_id

string

An optional ID for the room the service is located in. This field identifies the room across all merchants, services, and availability records. It also needs to be stable over time to allow correlation with past bookings. This field must be present if room_name is present.

room_name

string

An optional name for the room the service is located in. This field will be displayed to users making a booking, and should be human readable, as opposed to an opaque identifier. This field must be present if room_id is present.

party_size

int32

Applicable only for Dining: The party size which can be accommodated during this time slot. A restaurant can be associated with multiple Slots for the same time, each specifying a different party_size, if for instance 2, 3, or 4 people can be seated with a reservation.

SchedulingRules

The scheduling rules for a service.

Fields
min_advance_online_canceling

int64

The minimum advance notice in seconds required to cancel a booked appointment online. (optional)

late_cancellation_fee
(deprecated)

Price

The fee for canceling within the minimum advance notice period.

noshow_fee
(deprecated)

Price

The fee for no-show without canceling.

admission_policy

AdmissionPolicy

The admission policy that applies to this service. If unset, defaults to TIME_STRICT. (optional)

cancellation_policy

CancellationPolicy

Scheduling rules cancellation policy. (required for Things-to-do)

Union field min_booking_buffer. The duration (in seconds) from when the last booking can be made to when the availability slot starts or ends.

If "min_advance_booking" is set, the last bookable time is calculated as (<slot start time> - "min_advance_booking"). If "min_booking_buffer_before_end_time" is set, the last bookable time is calculated as (<slot end time> - "min_booking_buffer_before_end_time"). Note that the value of "min_booking_buffer_before_end_time" must be positive if set. If both are unset, the slot is bookable until the slot begin time.

Examples:

  • A haircut that needs to be booked at least 1 hour before the start time. 'scheduling_rules{ min_advance_booking: 3600 ...}`

  • A museum where the last ticket can be purchased 30 mins before closing: 'scheduling_rules{ min_booking_buffer_before_end_time: 1800 ...}'

  • A movie ticket that needs to be purchased before the start time. 'scheduling_rules{ ...}' (leave this field empty) (optional) min_booking_buffer can be only one of the following:

min_advance_booking

int64

The duration (in seconds) from when the last booking can be made to when the availability slot starts.

min_booking_buffer_before_end_time

int64

The duration (in seconds) from when the last booking can be made to when the availability slot ends. If this field is set, the "admission_policy" field must be set to TIME_FLEXIBLE to indicate that users can use the purchased tickets after slots start.

AdmissionPolicy

The admission policy of this service.

Enums
ADMISSION_POLICY_UNSPECIFIED Unused.
TIME_STRICT Customers are required to be present at the start time of the availability slot, and the service is expected to finish at the end time of the slot. Examples of TIME_STRICT use cases: * A tour that starts at 9am that requires all attendees to arrive at the start time, and returns at around 12pm. * A haircut reservation at 3pm on Saturday that will take approximately 30 minutes. * A fitness class from 6pm to 8pm.
TIME_FLEXIBLE

Customers can arrive at any time between the start and end time of the availability slot to use this booking.

Examples of TIME_FLEXIBLE use cases: * A museum ticket that can be used during any time on the purchase date. * An afternoon admission to an amusement park that can be used from 12pm to 9pm.

TIMED_ENTRY_WITH_FLEXIBLE_DURATION

Customers need to arrive at the merchant at the start time of the availability slot but can leave any time they want.

For example, in the museum admission scenario, a timed entry ticket for 10am requires the user to be at the museum at 10am. The start time of availability slots for this service represents the designated entry time. The end time, however, is used solely as a key to identify the availability slot for booking.

Service

Info about a service that is provided by the merchant, e.g. haircut. Next ID: 30

Fields
name

string

The service resource name, which has the format of partners/{partner_id}/merchants/{merchant_id}/services/{service_id}.

service_name

string

The name of the service, e.g. "Men's haircut". Deprecated, use localized_service_name instead.

localized_service_name

Text

The name of the service, e.g. "Men's haircut". Possibly in several locales.

description

string

The user-visible description of the service. Deprecated, use localized_description instead.

localized_description

Text

The user-visible description of the service.

This field supports both plain-text and HTML-like formatting. Unlike plain text sections, customized layouts can be created here using headings, paragraphs, lists and some phrase tags. Please read the following instructions and notes carefully to ensure you create the best user-experience.

Supported HTML-like formatting tags:

Heading tags: <h1>, <h2>, <h3>, <h4>, <h5>, <h6>
Heading tags can be used to display titles and sub-titles. For example, <h1>Itinerary</h1> will display the inline text as the most important heading of the section. Note that any inner HTML tags, styles or attributes will be ignored. For example, <h1 style=".."> will be treated the same as <h1>. Only pure text wil be preserved.

Paragraph tag: <p>
The paragraph tag can be used to highlight a detailed introduction or contents. Any inner tags, styles or attributes will be ignored, with a few exceptions: <br>, <strong> and <em>. Please see the phrase tag section below for more details.

List tags: <ul>, <ol>, <li>
The <ul> tag can be used with the <li> tag to display unordered lists, and the <ol> tag can be used with <li> to display ordered lists. This is a good way to display checklists, schedules, or any other lists that fit your use-cases.
Example: To show a list of features of a cruise trip:
<ol>
<li>Wonderful ocean view and chances to play with wildlife.</li>
<li>Carefully designed travel arrangements and services.</li>
<li>Gauranteed lowest price.</li>
</ol>
Note that only <li> children under <ul> or <ol> tags will be converted. All other children will be dropped. Also, any inner tags, attributes and styles will be ignored; we only preserve pure text contents.

Division tag: <div>
All supported inner tags of the <div> tag will be parsed with the rules stated above, imply <div> tag itself does not mean any grouping or indenting here. Also, any inner attributes and styles will be ignored.

Phrase tags: <br>, <strong>, <em>:
Only the three tags mentioned above are supported. <br> can be used to break lines in paragraphs, and <strong>/<em> can be used to highlight important text. Any other phrase tags will be ignored.

Unsupported tags:

  • <html>, <header>, and <body> tags are not allowed.
  • Any other tags not mentioned above are not supported (for example <table>, <td> ...).
    Any URLs, anchors, and links will be stripped, and will never be displayed to end-users. If you want to use photos to create a rich user experience, please use the "related_media" field below to send your photo URLs.

Important notes:

  • Try not to use other tags except for the supported ones mentioned above, because the contents within unsupported tags will be stripped, and may lead to an undesirable user experience.
  • Try avoid deep nested structures like more than 3 different heading levels or nested lists. Keeping the structure flat, simple, and straightforward, helps to create a better user experience.
  • If the currently supported layouts are not sufficient for your use cases, please reach out to the Reserve with Google team.
  • The recommended maximum size is 32,000 characters.

price

Price

The price of the service.

price_interpretation

PriceInterpretation

Describes how the price is interpreted and displayed to the user. Can be used by any vertical except Dining and Things To Do to configure display of the service price.

rules

SchedulingRules

Rules to book/cancel an appointment.

prepayment_type

PrepaymentType

Whether a prepayment is required, optional or not supported.

form[]
(deprecated)

ServiceIntakeForm

Intake forms to show to the user in order to customize the service.

Deprecated. Please see intake_form and per_ticket_intake_form.

intake_form

ServiceIntakeForm

A form requesting additional information from the user when they book this service. (optional)

per_ticket_intake_form

ServiceIntakeForm

A form requesting additional information from the user when they book this service. This form must be filled out once for each ticket the user is booking. (optional)

tax_rate

TaxRate

The service's tax rate. If present this field overrides any tax_rate set at the merchant level. An empty message (i.e. tax_rate { }) will reset the applied tax rate to zero.

payment_option_id[]

string

A list of ids referencing the payment options which can be used to pay for this service. The actual payment options are defined at the Merchant level, and can also be shared among multiple Merchants.

deposit

Deposit

Defines how a deposit may be charged to the user. Overrides the service deposit if one was specified. Setting this to an empty Deposit message removes any service-level deposit. (optional)

no_show_fee

NoShowFee

Defines a no show fee that may be charged to the user. Overrides the service no show fee if one was specified. Setting this to an empty NoShowFee message removes any service-level no show fee. (optional)

require_credit_card

RequireCreditCard

Indicates whether the user must provide a credit card in order to book this service. This field can be overridden at the availability level. (optional)

type

ServiceType

The predefined type of this service. (optional)

ticket_type[]

TicketType

Types of tickets that can be booked/purchased for this service, if tickets are supported. (optional)

related_media[]

RelatedMedia

Photos related to this service. Google will crawl and store the media to ensure that they are displayed to end-users in the most efficient way. (optional)

service_attribute_value_id[]

ServiceAttributeValueId

Service attribute values that apply to this service (optional). Each Service may have zero or more values for each service attribute defined in the corresponding Merchant. (optional)

waitlist_rules

WaitlistRules

Rules to joining the waitlist.

ticketing_vertical_specific_data

TicketingVerticalSpecificData

Additional information unique to the event ticketing vertical. (optional)

integration_type

IntegrationType

Depth of integration we support for this service. (optional) Irrelevant for partners with the starter integration. End to end will always be disabled for these partners.

per_order_fee

PerOrderFee

Order level fees for purchasing this service. (optional)

tours_and_activities_content

ToursAndActivitiesContent

Content fields specific to Tours and Activities.

location[]

Location

Locations related to this service. IMPORTANT NOTES: If there are multiple visited locations related to this service, or the START_LOCATION is different from the VISITED_LOCATION, the START_LOCATION must be specified. Example: - A guided biking tour visiting three venues, the start venue needs to be specified. - A bus tour meeting at a hotel lobby and then head to the visited venue. The meeting location needs to be specified.

rating

Rating

User rating for this service as an aggregate metric over all reviews.

PrepaymentType

Enum to indicate the prepayment type.

Enums
PREPAYMENT_TYPE_UNSPECIFIED By default we will assume that the prepayment is NOT_SUPPORTED.
REQUIRED The user has to pay this service at the booking time.
OPTIONAL The user can choose to pre-pay this service at the booking time or later, but it is not required in order to book.
NOT_SUPPORTED The prepayment is not supported for this service.

ServiceType

Predefined service types.

Enums
SERVICE_TYPE_UNSPECIFIED Unused.
SERVICE_TYPE_DINING_RESERVATION Dining reservation.
SERVICE_TYPE_FOOD_ORDERING Food ordering.
SERVICE_TYPE_EVENT_TICKET Event ticket.
SERVICE_TYPE_TRIP_TOUR Trip tour.
SERVICE_TYPE_APPOINTMENT Service that provides appointments or classes. Recommended for (1) health and fitness, (2) spa and beauty, and (3) financial consults and evaluations services. Please see the supported service types: https://developers.google.com/maps-booking/guides/end-to-end-integration/overview

ServiceAttribute

Service attributes are partner-defined categories that describe the Services for a Merchant. For example, a bank may define an "Account Type" service attribute with possible values of "Personal" and "Business", while a hair salon may define a "Service Type" service attribute with possible values of "Haircut", "Color", and "Style".

Fields
attribute_id

string

An identifier that uniquely identifies this service attribute among others for the same merchant, e.g. "account-type".

attribute_name

string

A user-visible name for this attribute, e.g. "Account Type".

value[]

Value

All possible values for this service attribute.

Value

Represents a possible value for a particular service attribute.

Fields
value_id

string

An identifier that uniquely identifies this value among others for this service attribute, e.g. "personal".

value_name

string

A user-visible name for the value, e.g. "Personal".

ServiceAttributeValueId

Identifies a particular value of a service attribute to be applied to a Service.

Fields
attribute_id

string

ID of an attribute as defined in Merchant.service_attribute, e.g. "service-type".

value_id

string

ID of the value for this attribute, e.g. "haircut". Must match a value_id in the service attribute definition.

ServiceAvailability

A list of availability and who/when they should be applied to.

Fields
name

string

The resource name of the service to apply this to. In the format of partners/{partner_id}/merchants/{merchant_id}/services/{service_id}

start_time_restrict

Timestamp

If provided, we will consider the Availability entities provided to be a complete snapshot from [start_time_restrict, end_time_restrict). That is, all existing availability will be deleted if the following condition holds true:

   start_time_restrict <= availability.start_sec &&
   availability.start_sec < end_time_restrict

If a duration message is set, the condition is further restricted:

  availability.duration == duration_restrict

If a resources_restrict message is set, the condition is further restricted:

   availability.resources.staff_id == resources_restrict.staff_id &&
   availability.resources.room_id == resources_restrict.room_id

These fields are typically used to provide a complete update of availability in a given time range.

Setting start_time_restrict while leaving end_time_restrict unset is interpreted to mean all time beginning at start_time_restrict.

end_time_restrict

Timestamp

Setting end_time_restrict while leaving start_time_restrict unset is interpreted to mean all time up to the end_time_restrict.

duration_restrict

Duration

Setting duration further restricts the scope of the update to just the availability with matching duration.

resources_restrict

Resources

Setting resources_restrict further restricts the scope of the update to just this set of resources. All id fields of the resources must match exactly.

availability[]

Availability

The new list of availability.

ServiceIntakeForm

Defines an intake form that customizes the service provided by a merchant.

Fields
field[]

ServiceIntakeFormField

Fields that will be displayed to the user.

first_time_customers
(deprecated)

bool

If true, this form will be shown to first time customers. Deprecated. This functionality is not supported for intake forms.

returning_customers
(deprecated)

bool

If true, this form will be shown to repeat customers. Deprecated. This functionality is not supported for intake forms.

ServiceIntakeFormField

Defines a field that is included in a ServiceIntakeForm.

Fields
id

string

A string from an aggregator partner which uniquely identifies a form field. This id should be the same as the id in the corresponding form field answer and must be unique across both the service level and per ticket intake forms. (required)

type

FieldType

The type of this field.

label

string

The text shown to the user for this field. Deprecated, please use localized_label instead.

localized_label

Text

The text shown to the user for this field. The field can be supplied in multiple locales. (required)

value[]

string

For MULTIPLE_CHOICE, CHECKBOXES, or DROPDOWN, the values to enumerate. For LOCATION_SEARCH, the values are locations. Please use the "location_id" in the "location" field to specify the location value.

is_required

bool

Indicates whether an answer to this field is required by a user.

ticket_type_restrict[]

string

If this question should only be shown when the user books certain ticket types, this field should be set as the set of applicable ticket type ids. Leave the field empty if the question is always applicable.

FieldType

Enum to indicate the type of field.

Enums
FIELD_TYPE_UNSPECIFIED Fields of unspecified or unknown type will be ignored.
SHORT_ANSWER A one-line input field for text.
PARAGRAPH A multi-line input field for text.
MULTIPLE_CHOICE A set of radio buttons that requires one choice from many options.
CHECKBOXES One or more enumerated items with checkboxes.
DROPDOWN A selection from a dropdown.
BOOLEAN A yes/no button.

TaxRate

A tax rate applied when charging the user for a service, and which can be set on either a per merchant, or per service basis.

Fields
micro_percent

int32

A tax rate in millionths of one percent, effectively giving 6 decimals of precision. For example, if the tax rate is 7.253%, this field should be set to 7253000.

If this field is left unset or set to 0, the total price charged to a user for any service provided by this merchant is the exact price specified by Service.price. The service price is assumed to be exempt from or already inclusive of applicable taxes. Taxes will not be shown to the user as a separate line item.

If this field is set to any nonzero value, the total price charged to a user for any service provided by this merchant will include the service price plus the tax assessed using the tax rate provided here. Fractions of the smallest currency unit (for example, fractions of one cent) will be rounded using nearest even rounding. Taxes will be shown to the user as a separate line item.

Terms

A set of rules and guidelines that are displayed to the user in order to make a booking through Reserve with Google.

Fields
url

string

Optionally, the URL to the Terms and Conditions.

text

string

The text to be displayed to the user. Use localized_text below for new integrations.

localized_text

Text

The localized text to be displayed to the user.

Text

A possibly-localized text payload. Some Text fields may contain marked-up content.

Fields
value

string

Text value in an unknown locale. Required if and only if localized_value is empty. The locale for this value may depend on the partner or service provider -- it should not be assumed to be any specific language.

localized_value[]

LocalizedString

Per-locale text values. Optional.

TicketType

TicketType is used to differentiate among tickets with different prices and/or availabilities due to different user types, different service attributes, or different options/add-ons.

A ticket is the minimal bookable unit to a service, e.g. a spot on a rafting trip, an admission to a museum, a full day double kayak rental.

Fields
ticket_type_id

string

The ticket id is used to differentiate among different ticket types of the same service, and is only expected to be unique within a service.

short_description

string

A short description to this TicketType.

This can be user visible, e.g., “adult”, "child", “veteran”, “Row J”, etc. Required, each ticket type should have a description to be user visible. Deprecated, use localized_short_description instead.

localized_short_description

Text

A short description to this TicketType with i18n support.

This can be user visible, e.g., “adult”, "child", “veteran”, “Row J”, etc. Required, each ticket type should have a description to be user visible. Separate values could be supplied for each locale.

price

Price

The price of a single ticket of this type, exclusive of any taxes. The tax rate of Service is applied to its tickets.

per_ticket_fee

PerTicketFee

Additional fees for purchasing this ticket. (optional)

option_description

string

Description of any additional option which this ticket type represents, if any. Deprecated, use localized_option_description instead.

localized_option_description

Text

Description of any additional option which this ticket type represents, if any. Separate values could be supplied for each locale.

Additional options are useful when the ticket type represents multiple dimensions.

Example 1: an admission ticket with different types 'adult', 'child' and language as an additional option, the expected TicketType list would be: - { ticket_type_id: "ticket_type_1" localized_short_description { value: "adult" } localized_option_description { value: "english" } } - { ticket_type_id: "ticket_type_2" localized_short_description { value: "adult" } localized_option_description { value: "spanish" } } - { ticket_type_id: "ticket_type_3" localized_short_description { value: "child" } localized_option_description { value: "english" } } - { ticket_type_id: "ticket_type_4" localized_short_description { value: "child" } localized_option_description { value: "spanish" } }

Example 2: an multi-hour kayak rental with optional dry bag add-on, the short_description could be "3 hours" and the option_description could be either "with dry bag" or "without dry bag": - { ticket_type_id: "ticket_type_1" localized_short_description { value: "2 hours" } localized_option_description { value: "english" } } - { ticket_type_id: "ticket_type_2" localized_short_description { value: "2 hours" } localized_option_description { value: "spanish" } } - { ticket_type_id: "ticket_type_3" localized_short_description { value: "3 hours" } localized_option_description { value: "english" } } - { ticket_type_id: "ticket_type_4" localized_short_description { value: "3 hours" } localized_option_description { value: "spanish" } }

Optional, but if any ticket type within the service has this field set, we expect all other ticket types to have this field set as well (a default option_description could be used). E.g. [{ticket_type_1, adult, english}, {ticket_type_1, adult, ''}] is not a valid list.

Only two HTML formatting tags are supported: and
. They are intended to be used for specifying options with both a title and detailed description, for example: "Premium Seating
This option offers seating at the private boxes including fully cushioned seats, private TVs, in-seat food and beverage service. These seats provide picturesque views of the field."

TicketingVerticalSpecificData

Additional information unique to the event ticketing vertical.

Fields
event_category

EventCategory

The category of the event. Set only when event falls into one of the predefined categories. (optional)

event_url

string

The URL of the event on the partner's website. (optional)

entity[]

Entity

A list of entities related to the event. (optional)

Entity

Represents an entity related to the event.

Fields
id

string

Unique identifier of the entity in the partner's database. (optional)

name

string

Name of the entity. (required)

url

string

Url of the webpage that unambiguously describes the entity. This is the webpage on the partner's website for the entity if any; for other public URLs of the entity, use relevant_url in public_identification_data. (optional)

entity_type

EntityType

The type of the entity. (optional)

entity_role

EntityRole

The role of the entity in the event. (optional)

public_identification_data

PublicIdentificationData

Public references of the entity. (optional)

EntityRole

The role of the entity in the event.

Enums
ENTITY_ROLE_UNSPECIFIED Not specified.
ENTITY_ROLE_HEADLINER The entity represents a headliner or leading performer at the event.
ENTITY_ROLE_SUPPORTER The entity represents a supporting performer at the event.
ENTITY_ROLE_HOME_TEAM The entity represents the home team at the (sports) event.
ENTITY_ROLE_AWAY_TEAM The entity represents the away team at the (sports) event.

EntityType

The type of the entity. Note: not intended to be a universal ontology.

Enums
ENTITY_TYPE_UNSPECIFIED Not specified. Do not use.
ENTITY_TYPE_PERFORMER The entity represents the artist or group performing at a concert or a show. Only applicable when event category is CONCERT or THEATRE.
ENTITY_TYPE_PLAYER The entity represents the sports team or player at the event. Only applicable when event category is SPORTS.
ENTITY_TYPE_CONCERT_TOUR The entity represents the tour that this event belongs to. Only applicable when event category is CONCERT.
ENTITY_TYPE_SPORTS_SERIES The entity represents a sports tournament that this event belongs to. Only applicable when event category is SPORTS.
ENTITY_TYPE_PLAY The entity represents the type of play (e.g., musical, comedy, ballet, etc.) performed at the event. Only applicable when event category is THEATRE.

EventCategory

A subset of event categories for which we customize the product experience. Note: not intended to be a universal ontology of events.

Enums
EVENT_CATEGORY_UNSPECIFIED Not specified. Do not use.
EVENT_CATEGORY_CONCERT Concerts.
EVENT_CATEGORY_SPORTS Sports events.
EVENT_CATEGORY_THEATRE Theatre events.
EVENT_CATEGORY_EXHIBITS Exhibits.
EVENT_CATEGORY_WORKSHOPS_AND_CLASSES Workshops and Classes.

PublicIdentificationData

Identifiers, webpages, or any other public sources that refernece an entity.

Fields
relevant_url[]

string

Public URL of any webpage that is dedicated to only the topic. This could include official websites, discogs, social media platforms, wikipedia or imdb pages, e.g. https://www.discogs.com/artist/1124645-Taylor-Swift, https://www.wikidata.org/wiki/Q19320959, https://twitter.com/acmilan. (optional)

musicbrainz_id

string

The 36-character musicbrainz identifier of the artist or other music entities, if applicable. See https://musicbrainz.org/doc/MusicBrainz_Identifier. (optional)

TimeRange

A closed-open time range, i.e. [start_time, end_time).

Fields
start_time

Timestamp

The lower bound of the time range.

end_time

Timestamp

The upper bound of the time range.

TokenizationConfig

A configuration for payment-processor tokenization, set up on a per-Merchant basis.

Fields
tokenization_parameter

map<string, string>

A tokenization configuration will typically have one tokenization_parameter whose key is "gateway" and whose value is the name of the processor.

The rest of the parameters are dependent on the processor. See Google Pay's documentation for further information.

Braintree example: tokenization_parameter { key: "gateway" value: "braintree" } tokenization_parameter { key: "braintree:apiVersion" value: "v1" } tokenization_parameter { key: "braintree:sdkVersion" value: "2.30.0" } tokenization_parameter { key: "braintree:merchantId" value: "abcdef" } tokenization_parameter { key: "braintree:clientKey" value: "production_xxx_yyy" }

Stripe example: tokenization_parameter { key: "gateway" value: "stripe" } tokenization_parameter { key: "stripe:version" value: "2018-02-28" } tokenization_parameter { key: "stripe:publishableKey" value: "pk_1234" }

Adyen example: tokenization_parameter { key: "gateway" value: "adyen" } tokenization_parameter { key: "gatewayMerchantId" value: "yourId" }

billing_information_format

BillingInformationFormat

Include in the payment token the user's billing information as entered into Google Pay with their FOP (see above). Leaving the field empty is equivalent to specifying MIN.

BillingInformationFormat

How much of the Billing Address to require of the user and include in the token. The enum values correspond to parameters in the Google Pay API (see https://developers.google.com/pay/api/web/reference/object#BillingAddressParameters).

Enums
BILLING_INFORMATION_FORMAT_UNSPECIFIED Not specified. Defaults to MIN.
MIN name, country code, and postal code (Google Pay default setting).
FULL name, street address, locality, region, country code, and postal code.

ToursAndActivitiesContent

Content fields specific to Tours and Activities. Each element in the repeated field should be independent to allow separate rendering (e.g. as a bullet point).

Populating ToursAndActivitiesContent is strongly recommended for tours and activities, but not strictly required. All fields support both plain-text and HTML-like text for basic formatting. Supported HTML-like formatting tags:

Phrase tags:
, , , : Only the three tags mentioned above are supported.
can be used to break lines in paragraphs, and // can be used to highlight an important text. Any other phrase tags will be ignored.

All other tags and custom styles are not allowed and will be removed. Any URLs, anchors, and links will be stripped, and will never be displayed to end-users.

Important notes: * Don't duplicate data already supplied in highlights, exclusion and other, more specific, fields in the service description. * Avoid using other tags except for the supported ones mentioned above, because the contents within unsupported tags will be stripped, and may lead to an undesirable user experience.

Fields
highlights[]

Text

The user-visible list of highlights.

inclusions[]

Text

The user-visible list of inclusions.

exclusions[]

Text

The user-visible list of exclusions.

must_know[]

Text

The user-visible list of important notes, use for details such as age restrictions or other conditions that make this service unsuitable.

UpdateBookingRequest

Request to update a google.maps.booking.v1alpha.Booking

Fields
update_mask

FieldMask

Field mask of all booking fields to be updated

booking

Booking

The booking to be updated

booking_failure

BookingFailure

If processing of an asynchronously confirmed booking request fails and the booking's status is being updated to FAILED, this field should reflect the business logic error (e.g., user has an existing reservation too close to this time). This field should only be set when updating the booking status to FAILED and will be ignored otherwise.

UpdateMerchantRequest

The request to update a Merchant.

Fields
merchant

Merchant

The new merchant data.

update_mask

FieldMask

The specific fields to update for the merchant.

UpdateOrderRequest

Request to update a google.maps.booking.v1alpha.Order

Fields
update_mask

FieldMask

Field mask of all order fields to be updated

order

Order

The order to be updated

UpdateServiceRequest

The request to update a Service.

Fields
service

Service

The new service data.

update_mask

FieldMask

The specific fields to update for the service.

UserPurchaseRestriction

Restricts the users eligible to purchase a payment option.

Fields
new_to_merchant

bool

A payment option that can only be purchased by users who have never purchased from the same merchant before.

new_to_payment_option

bool

A payment option that can only be purchased by users who have never purchased the same payment option before.

WaitlistRules

Rules related to joining the waitlist.

Fields
min_party_size

int32

Required. Must be a positive integer for services providing waitlist functionality. If the service or merchant does not provide waitlist functionality, this must not be populated.

max_party_size

int32

Required. Must be a positive integer for services providing waitlist functionality. If the service or merchant does not provide waitlist functionality, this must not be populated.

supports_additional_request

bool

If true, the user will be able to send a free-form additional text request when joining the waitlist for this service.