blob: 442dbc7a9cafb17996ff4f1d210380ec63a1329b [file] [log] [blame]
// API v3 public interface declaration
syntax = "proto3";
package ext.maps.booking.partner.v3;
// +------+------------------------------+----------------------------------+
// | Verb | HTTP Path | Request/Response Body |
// +------+------------------------------+----------------------------------+
// | GET | /v3/HealthCheck | - |
// | | | - |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CheckAvailability | CheckAvailabilityRequest |
// | | | CheckAvailabilityResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CreateBooking | CreateBookingRequest |
// | | | CreateBookingResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/UpdateBooking | UpdateBookingRequest |
// | | | UpdateBookingResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/GetBookingStatus | GetBookingStatusRequest |
// | | | GetBookingStatusResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/ListBookings | ListBookingsRequest |
// | | | ListBookingsResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CheckOrderFulfillability | CheckOrderFulfillabilityRequest |
// | | | CheckOrderFulfillabilityResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CreateOrder | CreateOrderRequest |
// | | | CreateOrderResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/ListOrders | ListOrdersRequest |
// | | | ListOrdersResponse |
// +------+------------------------------+----------------------------------+
// CheckAvailability method
// Request to check availability for a Slot.
message CheckAvailabilityRequest {
// The appointment slot that is being checked (required)
Slot slot = 1;
}
// Response for the CheckAvailability RPC with the availability of the
// appointment slot.
message CheckAvailabilityResponse {
// The requested slot. (required)
Slot slot = 1;
// Number of available spots.
// 0 indicates that the appointment slot is not available. (required)
int32 count_available = 2;
// If set, the last time (in seconds since the Unix epoch) that this specific
// appointment slot can be cancelled through Reserve with Google. This field
// will override any service-level cancellation rules. (optional)
int64 last_online_cancellable_sec = 5;
// This enum indicates what requirements exist for the user to acknowledge or
// view the requested slots duration/end time.
enum DurationRequirement {
// The handling of the end time is not specified. This is the default.
DURATION_REQUIREMENT_UNSPECIFIED = 0;
// The end time is not shown to the user.
DO_NOT_SHOW_DURATION = 1;
// The end time has to be shown to the user before an appointment can be
// made.
MUST_SHOW_DURATION = 2;
}
// The requirement to show the slots duration and/or endtime. This field will
// be ignored if the slot is unavailable. (optional)
DurationRequirement duration_requirement = 3;
// Optionally, the partner can return additional updated information about the
// availability for this merchant if this information is present when
// responding to the CheckAvailabilityRequest and if there is no negative
// impact on the CheckAvailability request latency.
// For instance an entire day of merchant availability for a superset of
// resources can be returned here.
AvailabilityUpdate availability_update = 4;
}
// An update to one ore more slots indicating that the availability for the
// associated time has potentially changed.
message AvailabilityUpdate {
repeated SlotAvailability slot_availability = 1;
}
// An inventory slot and associated count of open spots.
message SlotAvailability {
Slot slot = 1;
// Number of available spots.
// 0 indicates that the appointment slot is not available. (required)
int32 count_available = 2;
}
// BatchAvailabilityLookup method
// Identifies a Slot service_id and start time and optionally, the Slot duration
// and resources, for a specific merchant. Note that this differs from the
// definition of Slot, as it does not include merchant_id identifier.
message SlotTime {
// ID of the service. (required)
string service_id = 5;
// Start time of the appointment slot in seconds of UTC time since Unix epoch
// (required)
int64 start_sec = 1;
// Duration of the appointment slot in seconds (optional)
int64 duration_sec = 2;
// Opaque tag that identifies the availability slot and matches the value
// provided in the availability feed (optional)
string availability_tag = 3;
// The set of resources that specifies the appointment slot, e.g. by
// indicating the staff member and room selected by the user, or party size
// for dining slots (optional)
ResourceIds resource_ids = 4;
}
message SlotTimeAvailability {
// The SlotTime for which availability was checked.
SlotTime slot_time = 1;
// Whether the requested SlotTime is available
bool available = 2;
}
// Request to lookup availabilities of a list of specified slot times for a
// given merchant/service.
message BatchAvailabilityLookupRequest {
// ID of the merchant.
string merchant_id = 1;
// Multiple slot times to be checked for availability. All queried times apply
// to the same merchant_id and service_id.
repeated SlotTime slot_time = 3;
reserved 2;
}
// Response for the BatchAvailabilityLookupRequest RPC with the availabilities
// of the appointment slots.
message BatchAvailabilityLookupResponse {
// The availabilities for the requested SlotTime entries. There must be
// exactly one slot_time_availability for each SlotTime entry in the
// [ext.maps.booking.partner.v3.BatchAvailabilityLookupRequest].
repeated SlotTimeAvailability slot_time_availability = 1;
}
// CheckOrderFulfillability method
// Request to check the fulfillability of an order.
message CheckOrderFulfillabilityRequest {
// The merchant that this order is intended for. (required)
string merchant_id = 1;
// The line items in this order. All services requested must belong to the
// specified merchant. (required)
repeated LineItem item = 2;
}
// Response for the CheckOrderfulfillabilityRequest.
message CheckOrderFulfillabilityResponse {
// Fulfillability status of the order, potentially contains updated
// availabilities and prices of the requested line item. (required)
OrderFulfillability fulfillability = 1;
// Total processing fees & taxes that need to be paid for this order.
// (required) This field will be deprecated; new users should populate fees
// instead.
Price fees_and_taxes = 2;
// Breakdown of the specific per-ticket and per-order fees and taxes.
Fees fees = 3;
// Time at which the cart will expire and its contents will no longer be
// available, in unix epoch time (optional).
// If not set, a default value will be used and the cart will not expire.
int64 cart_expiration_sec = 4;
}
// GetBookingStatus method
// Request to get booking status and prepayment status for a Booking.
message GetBookingStatusRequest {
// ID of the existing booking (required)
string booking_id = 1;
}
// Response for the GetBookingStatus RPC with booking status and prepayment
// status.
message GetBookingStatusResponse {
// ID of the booking (required)
string booking_id = 1;
// Status of the booking (required)
BookingStatus booking_status = 2;
// Prepayment status of the booking (required)
PrepaymentStatus prepayment_status = 3;
}
// CreateBooking method
// Request to create a Booking for an inventory slot. Consumes the lease if
// provided.
message CreateBookingRequest {
// The inventory slot that is being requested to make this booking.
// If lease_ref is provided, slot must match the lease; slot is provided for
// the partner to verify the lease information.
// If lease_ref is absent, then create the booking for the slot. (required)
Slot slot = 1;
// The lease that is being confirmed to make this booking.
// If lease_ref is provided, then create the booking using the lease.
// (optional)
LeaseReference lease_ref = 2;
// Personal information of the user making the appointment (required)
UserInformation user_information = 3;
// Information about payments. When payment authorizations are handled by
// Google, if the booking request does not succeed, payment authorizations are
// automatically canceled. (optional)
PaymentInformation payment_information = 4;
// The parameters to be used if the payment is processed by the partner
// (i.e. payment_information.payment_processed_by is equal to
// PROCESSED_BY_PARTNER). (optional)
PaymentProcessingParameters payment_processing_parameters = 5;
// Idempotency token for CreateBooking requests. (required)
string idempotency_token = 6;
// A string from the user which contains any special requests or additional
// information that they would like to notify the merchant about. (optional)
string additional_request = 7;
}
// Response with the created Booking for an inventory slot.
message CreateBookingResponse {
// The created booking (required)
Booking booking = 1;
// The updated user payment option used in this booking.
// If a new payment option was purchased to pay for the booking, this should
// be a newly created user payment option.
// If an already purchased user payment option was used for this booking,
// this should reflect an updated version of that user payment option.
// (optional)
UserPaymentOption user_payment_option = 2;
// If creating a booking fails, this field should reflect the business logic
// error (e.g., slot has become unavailable) and all other fields in the
// CreateBookingResponse message are expected to be unset. (required if
// failure occurs)
BookingFailure booking_failure = 3;
}
// CreateLease method
// Request to create a Lease for a slot in the inventory. The expiration time
// in the returned Lease may be modified by the backend, e.g. if the requested
// lease period is too long.
message CreateLeaseRequest {
// The lease to be created with information about the appointment slot
// (required)
Lease lease = 1;
}
// Response for the CreateLease RPC with the created Lease.
message CreateLeaseResponse {
// The created Lease (required)
Lease lease = 1;
// If creating a lease fails, this field should reflect the business logic
// error (e.g., slot has become unavailable) and lease field is expected to be
// unset. (required if failure occurs)
BookingFailure booking_failure = 2;
}
// Temporary lease for an inventory slot
message Lease {
// ID of the lease.
// Not populated in CreateLeaseRequest. The value is chosen by the partner and
// has to be returned in the response of CreateLease. (required)
string lease_id = 1;
// The appointment slot that the lease is created for. (required)
Slot slot = 2;
// Unique identifier for this lease, chosen by Reserve with Google. Serves as
// an idempotency token for CreateLease requests. (required)
string user_reference = 3;
// Expiration time of the lease in UTC Timestamp (required)
int64 lease_expiration_time_sec = 4;
}
// Reference to a Lease that has been created via CreateLease.
message LeaseReference {
// Lease ID (required)
string lease_id = 1;
}
// CreateOrder method
// Request to create an order.
message CreateOrderRequest {
// The order to create. (required)
Order order = 1;
// The parameters to be used if the payment is processed by the partner
// (i.e. order.payment_information.payment_processed_by is equal to
// PROCESSED_BY_PARTNER). (required if payment is processed by the partner)
PaymentProcessingParameters payment_processing_parameters = 2;
// Idempotency token for CreateOrder requests. (required)
string idempotency_token = 3;
}
// Response for the CreateOrderRequest.
message CreateOrderResponse {
// All line items in an order either fail or succeed together.
// This means that if some of the items cannot be fulfilled, the entire
// order must fail, the booking must not be made for any item, and the user
// must not be charged.
oneof result {
// The order created.
Order order = 1;
// If creating an order fails, this field should reflect the business logic
// error (e.g., slot has become unavailable or price has changed).
OrderFailure order_failure = 2;
}
}
// ListBookings method
// Request to list all bookings for a user
message ListBookingsRequest {
// ID of the user (required)
string user_id = 1;
}
// Response for the ListBookings RPC with all bookings for the requested user.
message ListBookingsResponse {
// All bookings of the user (required)
repeated Booking bookings = 1;
}
// ListOrders method
// Request to list orders.
message ListOrdersRequest {
message OrderIds {
repeated string order_id = 1;
}
// Request of orders either by user ID, or by order ID.
oneof ids {
// If set, return all orders belong to the user.
string user_id = 1;
// If set, return the specified orders.
OrderIds order_ids = 2;
}
}
// Response for the ListOrders RPC.
message ListOrdersResponse {
// All requested orders (required)
repeated Order order = 1;
}
// UpdateBooking method
// Request to update a Booking.
message UpdateBookingRequest {
// The booking to be updated
// The following fields can be set in a booking:
// - status, to cancel a booking.
// - one of the following is required:
// - start_time AND duration in the slot, to reschedule a booking.
// - party_size (for dining reservations).
Booking booking = 1;
}
// Response with the updated Booking.
message UpdateBookingResponse {
// The updated booking (required)
Booking booking = 1;
// The updated user payment option originally used to pay for this booking.
// This should be set if the UpdateBookingRequest results in a change to
// the UserPaymentOption.
// For instance, if the booking is canceled, the UserPaymentOption should
// reflect an additional credit to the user. In the case of a multi-use
// payment option, the current_count should be increased by one to
// allow the user to create another booking with this payment option. In the
// case of a single-use payment option, a new single-use user payment option
// should be returned. (required if altered in update)
UserPaymentOption user_payment_option = 2;
// If updating a booking fails, this field should reflect the business logic
// error (e.g., booking is not cancellable) (required if failure occurs)
BookingFailure booking_failure = 3;
}
// Booking specification
// A booking for an inventory slot
message Booking {
// ID of this booking (required)
string booking_id = 1;
// The appointment slot of this booking (required)
Slot slot = 2;
// Personal information of the user making the appointment (required)
UserInformation user_information = 3;
// Status of the booking (required)
BookingStatus status = 4;
// Information about payment transactions that relate to the booking.
// (optional)
PaymentInformation payment_information = 5;
}
// BookingStatus specification
// Status of a booking.
//
// Updating booking status does not change the status of the associated payment.
// Prepayment status updates should be done using the PrepaymentStatus enum.
//
// nextID: 8
enum BookingStatus {
// Not specified.
BOOKING_STATUS_UNSPECIFIED = 0;
// Booking has been confirmed
CONFIRMED = 1;
// Booking is awaiting confirmation by the merchant before it can transition
// into CONFIRMED status
PENDING_MERCHANT_CONFIRMATION = 2;
// Booking has been canceled on behalf of the user.
// The merchant can still trigger a manual refund.
CANCELED = 3;
// User did not show for the appointment
NO_SHOW = 4;
// User did not show for the appointment in violation of the cancellation
// policy.
NO_SHOW_PENALIZED = 5;
// Booking could not be completed by the backend due to a failure.
FAILED = 6;
// Booking was asynchronously declined by the merchant.
DECLINED_BY_MERCHANT = 7;
}
// Information about payment failures.
message PaymentFailureInformation {
// Parameters requesting that RwG perform a 3DS1 challenge.
//
// The parameters are set by EMVCo's description of the 3DS1 protocol.
message ThreeDS1Parameters {
// The URL from which to load a form to present to the User for
// authentication.
string acs_url = 1;
// A PaymentAuthentication Request. To be posted to the ACSUrl form if
// supplied.
string pa_req = 2;
// An identifier used by the ACS provider. To be posted to the ACSUrl
// form if supplied.
string transaction_id = 3;
// Merchant data. To be posted to the ACSUrl form if supplied.
string md_merchant_data = 4;
}
// Parameters used by a RwG aggregator to initiate a 3DS1 authentication
// protocol with the user. Will be ignored unless
// {Booking|Order}Failure.cause is set to PAYMENT_REQUIRES_3DS1.
ThreeDS1Parameters threeds1_parameters = 5;
}
// BookingFailure specification
// Status data that conveys why (1) creating a lease or (2) creating or updating
// a booking fails.
// BookingFailure is intended to primarily capture business logic errors.
message BookingFailure {
enum Cause {
// Default value: Don't use; amounts to an "unknown error"
CAUSE_UNSPECIFIED = 0;
// The referenced availability slot is not available any longer.
SLOT_UNAVAILABLE = 1;
// The user has already booked an appointment for the referenced
// availability slot.
SLOT_ALREADY_BOOKED_BY_USER = 2;
// The lease (if provided) has expired and cannot be used any longer to
// complete the requested booking.
LEASE_EXPIRED = 3;
// The requested cancellation cannot be performed at the current time due
// to time restrictions in the merchant's cancellation policy.
OUTSIDE_CANCELLATION_WINDOW = 4;
// 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_TYPE_REJECTED = 5;
// An error was encountered while processing the payment because the
// provided credit card was declined.
PAYMENT_ERROR_CARD_DECLINED = 6;
// 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_OPTION_NOT_VALID = 7;
// 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.
PAYMENT_ERROR = 8;
// User cannot use the given payment option (e.g. user trying to use a
// first time price for the second time).
USER_CANNOT_USE_PAYMENT_OPTION = 9;
// A booking that the user tried to cancel has already been cancelled.
BOOKING_ALREADY_CANCELLED = 10;
// A booking that the user tried to cancel is not cancellable.
BOOKING_NOT_CANCELLABLE = 11;
// User has an existing reservation too close to this time.
OVERLAPPING_RESERVATION = 12;
// 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.
PAYMENT_REQUIRES_3DS1 = 15;
}
// The reason why the booking failed. (required)
Cause cause = 1;
// (required only if cause is PAYMENT_ERROR_CARD_TYPE_REJECTED)
CreditCardType rejected_card_type = 2;
// This optional field is used for the partner to include additional
// information for debugging purpose only. (optional)
string description = 3;
// Details about payment failures.
PaymentFailureInformation payment_failure = 4;
}
// Used when booking/order failure cause is PAYMENT_ERROR_CARD_TYPE_REJECTED to
// indicate the type of credit card that was rejected.
enum CreditCardType {
// Default value. Used if credit card type does not match to one below.
CREDIT_CARD_TYPE_UNSPECIFIED = 0;
VISA = 1;
MASTERCARD = 2;
AMERICAN_EXPRESS = 3;
DISCOVER = 4;
JCB = 5;
}
// Mode by which bookings for an availability slot are confirmed.
enum ConfirmationMode {
// The confirmation mode was not specified.
// Synchronous confirmation will be assumed.
CONFIRMATION_MODE_UNSPECIFIED = 0;
// Bookings for this availability will be confirmed synchronously.
CONFIRMATION_MODE_SYNCHRONOUS = 1;
// Bookings for this availability will be confirmed asynchronously.
CONFIRMATION_MODE_ASYNCHRONOUS = 2;
}
// Order specification
// An order for service appointments with a merchant.
message Order {
// ID of this Order, chosen by the booking partner who handles the order
// (required in CreateOrderResponse and ListOrdersResponse, must not be set in
// CreateOrderRequest)
string order_id = 1;
// Personal information of the user making the order (required)
UserInformation user_information = 2;
// Information about payment transactions that relate to the Order.
// (optional)
PaymentInformation payment_information = 3;
// The merchant that all services in this Order belong to.
string merchant_id = 4;
// Line items in this order.
repeated LineItem item = 5;
}
// A single item in an Order--the booking of a single service in a single time
// slot.
message LineItem {
// ID of the merchant Service. (required)
string service_id = 1;
// Start time of the appointment slot in seconds of UTC time since Unix epoch.
// (required)
int64 start_sec = 2;
// Duration of the appointment slot in seconds. (required)
int64 duration_sec = 3;
message OrderedTickets {
string ticket_id = 1;
int32 count = 2;
}
// Number of tickets ordered by Ticket Type.
repeated OrderedTickets tickets = 4;
// In handling CreateOrderRequest and CheckOrderFulfillabilityRequest,
// the total price (excluding taxes) of the item must be verified to guard
// against price changes. In CreateOrderResponse and
// CheckOrderFulfillabilityResponse, the price should be updated to the
// correct value if the value from the request was incorrect or outdated.
// (required)
Price price = 5;
// Status of the Line Item. (required in CreateOrderResponse and
// ListOrdersResponse; should not be set in requests)
BookingStatus status = 6;
}
// Status data that conveys why creating an order fails.
// OrderFailure is intended to primarily capture business logic errors.
message OrderFailure {
enum Cause {
// Default value: Don't use; amounts to an "unknown error"
CAUSE_UNSPECIFIED = 0;
// The order is no longer fulfillable.
ORDER_UNFULFILLABLE = 1;
// 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_TYPE_REJECTED = 2;
// An error was encountered while processing the payment because the
// provided credit card was declined.
PAYMENT_ERROR_CARD_DECLINED = 3;
// An error was encountered while processing the payment for this order.
// Use this value to indicate a general payment related error, only if the
// error does not match to a specific payment error above.
PAYMENT_ERROR = 4;
// 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.
PAYMENT_REQUIRES_3DS1 = 5;
// The fee total in the request is incorrect or not up-to-date.
INCORRECT_FEE_TOTAL = 6;
}
// The reason why the order failed. (required)
Cause cause = 1;
// (required only if cause is ORDER_UNFULFILLABLE)
OrderFulfillability fulfillability = 2;
// (required only if cause is PAYMENT_ERROR_CARD_TYPE_REJECTED)
CreditCardType rejected_card_type = 3;
// This optional field is used for the partner to include additional
// information for debugging purpose only. (optional)
string description = 4;
// Details about payment failures.
PaymentFailureInformation payment_failure = 5;
}
// OrderFulfillability specification
message OrderFulfillability {
// The result of an order fulfillability check.
enum OrderFulfillabilityResult {
// Default value: Don't use.
ORDER_FULFILLABILITY_RESULT_UNSPECIFIED = 0;
// The order can be fulfilled.
CAN_FULFILL = 1;
// The order cannot be fulfilled due to one or more unfulfillable line
// item(s).
UNFULFILLABLE_LINE_ITEM = 2;
// The combination of the line items requested cannot be fulfilled.
UNFULFILLABLE_SERVICE_COMBINATION = 3;
// The order cannot be fulfilled due to reasons that do not fall into the
// categories above.
ORDER_UNFULFILLABLE_OTHER_REASON = 4;
}
OrderFulfillabilityResult result = 1;
// Fulfillability results of all line items in this order (required).
repeated LineItemFulfillability item_fulfillability = 2;
// Additional description of the reason if the item is unfulfillable.
// (optional)
string unfulfillable_reason = 3;
}
// Fulfillability of a line item.
message LineItemFulfillability {
// The line item of question. (required)
LineItem item = 1;
// The result of a line item fulfillability check.
enum ItemFulfillabilityResult {
// Default value: Don't use.
ITEM_FULFILLABILITY_RESULT_UNSPECIFIED = 0;
// This line item can be fulfilled.
CAN_FULFILL = 1;
// No adequate availability for the slot requested.
SLOT_UNAVAILABLE = 2;
// Child tickets cannot be booked without an adult ticket.
CHILD_TICKETS_WITHOUT_ADULT = 6;
// The combination of ticket types requested cannot be fulfilled.
UNFULFILLABLE_TICKET_COMBINATION = 3;
// The total price of this line item is not correct.
INCORRECT_PRICE = 4;
// The line item cannot be fulfilled for reasons that do not fall into
// the categories above.
ITEM_UNFULFILLABLE_OTHER_REASON = 5;
// The line item cannot be fulfilled since the number of tickets is less
// than the min ticket count specififed by the partner.
TICKET_CONSTRAINT_VIOLATED = 7;
}
// (required)
ItemFulfillabilityResult result = 2;
// Additional description of the reason if the item is unfulfillable.
// (optional)
string unfulfillable_reason = 3;
// Updated availability for this slot can be piggybacked in
// CheckOrderFulfillabilityResponse.
message UpdatedAvailability {
// Number of available spots for the given slot. 0 indicates no
// availability. (required)
int32 spots_open = 1;
}
// (optional)
UpdatedAvailability availability = 4;
// Updated ticket types can be piggybacked in
// CheckOrderFulfillabilityResponse. If non-empty, all available ticket types
// for this slot with up-to-date prices should be listed without omitting any.
// (optional)
repeated TicketType ticket_type = 5;
// This proto will represent all the constraints violated by the user.
// Below are all the ways in which a violated_constraint can be represented.
//
// 1 : Constraint violation for the entire line item.
// { violated_ticket_constraint : { min_ticket_count : 5 } }
//
// 2 : Constraint violation for a ticket type within a line item.
// { violated_ticket_constraint : { min_ticket_count : 5, ticket_id : "ttd1"}}
//
// 3 : Constraint violation for multiple ticket types within a line item.
// { violated_ticket_constraint : { min_ticket_count : 3, ticket_id : "ttd1"}}
// { violated_ticket_constraint : { min_ticket_count : 4, ticket_id : "ttd2"}}
//
// 4 : Constraint violation for entire line item as well as an override
// for multiple ticket types within the availability slot.
// { violated_ticket_constraint : { min_ticket_count : 8 } }
// { violated_ticket_constraint : { min_ticket_count : 3, ticket_id : "ttd1"}}
// { violated_ticket_constraint : { min_ticket_count : 4, ticket_id : "ttd2"}}
//
message ViolatedTicketConstraint {
oneof value {
int32 min_ticket_count = 1;
int32 max_ticket_count = 2;
}
reserved 3;
// The absence of ticket_type_ids indicates that this constraint applies to
// the entire line item.
string ticket_id = 4;
}
// This must be set if ItemFulfillabilityResult is TICKET_CONSTRAINT_VIOLATED.
repeated ViolatedTicketConstraint violated_ticket_constraint = 6;
}
// 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.
message TicketType {
// 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.
string ticket_type_id = 1;
// 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.
string short_description = 2;
// The price of a single ticket of this type, exclusive of any taxes. The tax
// rate of Service is applied to its tickets.
Price price = 3;
// Description of any additional option which this ticket type represents, if
// any.
//
// This is 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" short_description: "adult"
// option_description: "english" }
// - { ticket_type_id: "ticket_type_2" short_description: "adult"
// option_description: "spanish" }
// - { ticket_type_id: "ticket_type_3" short_description: "child"
// option_description: "english" }
// - { ticket_type_id: "ticket_type_4" short_description: "child"
// option_description: "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" short_description: "2 hours"
// option_description: "english" }
// - { ticket_type_id: "ticket_type_2" short_description: "3 hours"
// option_description: "spanish" }
// - { ticket_type_id: "ticket_type_3" short_description: "2 hours"
// option_description: "english" }
// - { ticket_type_id: "ticket_type_4" short_description: "3 hours"
// option_description: "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.
string option_description = 4;
}
// Other specifications
// Resource specification that disambiguates an appointment slot
message ResourceIds {
// The staff ID as provided in the feed or empty if not applicable or no staff
// was selected. (optional)
string staff_id = 1;
// The room ID as provided in the feed or empty if not applicable or no room
// was selected. (optional)
string room_id = 2;
// For Dining Reservations only: the number of seats requested in the booking.
// (optional)
int32 party_size = 3;
}
// A configuration for payment-processor tokenization, set up on a per-Merchant
// basis.
message TokenizationConfig {
// A tokenization configuration will typically have one
// tokenization_parameter whose key is "gateway" and whose value is the
// name of the processor.
map<string, string> tokenization_parameter = 1;
// Control how much billing information to include in the
// payment token.
enum BillingInformationFormat {
// Not specified. Defaults to MIN.
BILLING_INFORMATION_FORMAT_UNSPECIFIED = 0;
// name, country code, and postal code (Google Pay default setting).
MIN = 1;
// name, street address, locality, region, country code, and postal code.
FULL = 2;
}
// Include in the payment token the user's billing information as entered into
// Google Pay with their FOP (see above).
BillingInformationFormat billing_information_format = 2;
}
// Payment specification
message PaymentProcessingParameters {
enum PaymentProcessor {
PAYMENT_PROCESSOR_UNSPECIFIED = 0;
PROCESSOR_STRIPE = 1;
PROCESSOR_BRAINTREE = 2;
}
// The payment processor used to process payment for a given booking.
// (required)
//
// Replaced by the payment_processor field.
PaymentProcessor processor = 1 [deprecated = true];
// The token representing the payment method that will be used to pay
// for this booking. This token can be only used once. This token can be
// only used for the merchant associated with this booking.
//
// Each processor may choose its own format for this field.
// An example of Stripe's token is "tok_1C3orL2eZvKYlo2CxReMgS4K".
//
// Replaced by unparsed_payment_method_token, which contains
// payment_method_token as one of its fields.
// For example, for Stripe, unparsed_payment_method_token is a serialized
// JSON object documented at https://stripe.com/docs/api#token_object.
// payment_method_token is the 'id' field parsed out of that.
string payment_method_token = 2 [deprecated = true];
// The full token received from Google Payments. This is typically a
// serialized JSON object. See documentation from Google Payments and your
// payment processor for the JSON format of the token for your processor.
// https://developers.google.com/pay/api/#participating-google-pay-processors
//
// This token can only be used once, and only for the merchant associated with
// this booking.
string unparsed_payment_method_token = 5;
// The payment processor API version that the given payment token is valid
// for.
//
// Each processor may choose its own format for this field.
// Stripe uses a date (e.g. "2017-06-15"). (required)
// This is deprecated in favor of tokenization_parameters.
string version = 3 [deprecated = true];
// The payment processor whose configuration was used to generate this token.
// (required)
// This is deprecated in favor of tokenization_parameters.
string payment_processor = 4 [deprecated = true];
// The tokenization_config supplied in the Merchant feed that was used
// to generate unparsed_payment_method_token.
TokenizationConfig tokenization_config = 6;
}
enum PaymentOptionType {
PAYMENT_OPTION_TYPE_UNSPECIFIED = 0;
PAYMENT_OPTION_SINGLE_USE = 1;
PAYMENT_OPTION_MULTI_USE = 2;
PAYMENT_OPTION_UNLIMITED_USE = 3;
}
// This describes a payment option, such as a pack, membership, or
// single-session pass after it has been purchased by a user. It includes an
// identifier for the user payment option, as well as some information about
// the payment option with which it is associated.
message UserPaymentOption {
// A unique identifier for the user payment option. This Id MUST be unique
// for all UserPaymentOptions across all merchants and users. (required)
string user_payment_option_id = 1;
// The user payment option will be valid (usable) between start_time and
// end_time set in UTC. Attempts to use a user payment option to make a
// booking outside of this interval will fail. (both optional)
int64 valid_start_time_sec = 2;
int64 valid_end_time_sec = 3;
// The type of the payment option associated with this user payment option.
// This can be unlimited for a membership or subscription, multi-use for a
// pack, or single-use. (required)
PaymentOptionType type = 4;
// The original number of uses for this user payment option when it was
// purchased. This value is ignored for unlimited payment options. (required)
int32 original_count = 5;
// The number of uses remaining for this user payment option. If this number
// is 0 for a pack, attempts to use this payment option to make a booking will
// fail. (required)
int32 current_count = 6;
// The id of the payment option that has been used to purchase this user
// payment option. (required)
string payment_option_id = 7;
}
// Payment details that are sent when creating a new booking.
message PaymentInformation {
// Prepayment status of the booking.
// If the prepayment_status is PREPAYMENT_PROVIDED, then
// payment_transaction_id contains the associated unique transaction id for
// the purchase.
// If the prepayment status is PREPAYMENT_REFUNDED, then
// payment_transaction_id contains the associated unique transaction id for
// the refund. (required)
PrepaymentStatus prepayment_status = 1;
// Unique identifier for a payment transaction associated with the booking.
// If the payment is PROCESSED_BY_GOOGLE, this field will be set by Google.
// If the payment is PROCESSED_BY_PARTNER, this field will be left empty in
// Google's CreateBooking or CreateOrder requests to the partner, and it must
// be set by the partner in their responses.
string payment_transaction_id = 2;
// These fields must match the service price (specified in the Services feed)
// or the PaymentOption corresponding with this service.
// They are included in the booking request and response to verify that
// the price indicated in the feed has not changed since the last feed
// update.
//
// The price of the booking or order, exclusive of any taxes.
// Existence of price or taxes does not imply that they have been paid,
// prepayment_state should be used for that purpose. (required)
Price price = 3;
// Taxes that are calculated to be paid for this booking.
// This field can only be absent in one of the following cases:
// (1) the price is exempt from or already inclusive of applicable taxes; or
// (2) the break down between taxes and fees is not available.
// (required when neither of the above holds)
Price tax_amount = 4;
// Additional fees associated with this transaction, if any.
//
// The use of this field should be consistent with other pricing related
// fields:
// - if a {price, tax, fees} breakdown is provided for service or
// availability, use the same breakdown {price, tax, fees} here.
// - if the price field for service or availability already includes taxes
// or fees, keep using price field to includes taxes or fees and avoid
// setting the tax_amount or fees fields here.
Price fees = 11;
// Who handles payment processing?
// If payment is processed by the partner, CreateBooking request will
// include additional parameters (PaymentProcessingParameters) indicating
// the payment method to be used to process the payment.
enum PaymentProcessedBy {
PAYMENT_PROCESSED_BY_UNSPECIFIED = 0;
PROCESSED_BY_GOOGLE = 1;
PROCESSED_BY_PARTNER = 2;
}
// Whether the partner or Google processed the payment. (required)
PaymentProcessedBy payment_processed_by = 5;
// The id of the payment option or user payment option associated with the
// booking.
// If a payment option is purchased as part of a booking, payment_option_id
// will be set with the id of that payment option.
// If an already purchased user payment option is being used to pay for a
// booking, user_payment_option_id will be set with the id of that user
// payment option.
// When included as part of a response proto, the user_payment_option_id
// should be set and must match the UserPaymentOption that is returned in the
// RPC response (e.g. the user_payment_option returned in
// CreateBookingResponse). (one of these required)
oneof payment_id {
// The id of the payment option associated with this booking. If this field
// is populated, price (and tax_amount, if applicable) must be populated as
// well.
string payment_option_id = 6;
// The id of the user payment option used to pay for this booking.
string user_payment_option_id = 7;
}
// Defines how a deposit may be charged to the user. If there is a deposit,
// this field should be set. (optional)
Deposit deposit = 8;
// Defines a no show fee that may be charged to the user. If the user can be
// charged a no show fee, this field should be set. (optional)
NoShowFee no_show_fee = 9;
// Total processing fees & taxes that the user needs to pay for the order;
// only applicable to partners that handle order based booking (e.g., with
// CreateOrder method). (optional)
Price fees_and_taxes = 10;
}
// Prepayment status of a booking.
// Updating payment status will trigger an update on the payment status of the
// associated booking (if applicable).
// Currently, the only supported transition is from PREPAYMENT_PROVIDED to
// PREPAYMENT_REFUNDED, which will initiate a non-reversible refund on the
// associated payment transaction.
enum PrepaymentStatus {
// Not specified, defaults to PREPAYMENT_NOT_PROVIDED.
PREPAYMENT_STATUS_UNSPECIFIED = 0;
// The fee for the booking has been paid in advance.
PREPAYMENT_PROVIDED = 1;
// The fee for the booking has not been paid in advance.
PREPAYMENT_NOT_PROVIDED = 2;
// The fee was previously PREPAYMENT_PROVIDED but has now been refunded.
PREPAYMENT_REFUNDED = 3;
// The fee was previously PREPAYMENT_PROVIDED but now has been credited
// (user given a UserPaymentOption as a voucher for the booking).
// If this is set, the response should also include the updated
// UserPaymentOption.
PREPAYMENT_CREDITED = 4;
}
// The price of a service or a fee.
message Price {
// 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).
// (required)
int64 price_micros = 1;
// The currency of the price that is defined in ISO 4217. (required)
string currency_code = 2;
// An optional and opaque string that identifies the pricing option that is
// associated with the extended price. (optional)
string pricing_option_tag = 3;
}
// Defines how a total price is determined from an availability.
enum PriceType {
// The price is for a fixed amount. This is the default value if the field is
// not set.
FIXED_RATE_DEFAULT = 0;
// 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.
PER_PERSON = 1;
}
// A fee that a user may be charged if they have made a booking but do not
// show up.
message NoShowFee {
// The amount the user may be charged if they do not show up for their
// reservation.
Price fee = 1;
// Defines how the fee is determined from the availability.
PriceType fee_type = 3;
}
// The specific partner-named fees that must be paid for each ticket the user
// purchases.
message SpecificPerTicketFee {
// ID of a ticket type.
string ticket_id = 1;
// A localized partner-provided name for this fee or tax.
string fee_name = 2;
// The amount of the fee or tax.
Price fee_amount = 3;
}
// The specific partner-named fees that must be paid once per order, regardless
// of number of tickets.
message SpecificPerOrderFee {
// A localized partner-provided name for this fee or tax.
string fee_name = 1;
// The amount of the fee or tax.
Price fee_amount = 2;
}
// Breakdown of the specific, partner-named per-ticket and per-order fees and
// taxes.
message Fees {
// Fees and taxes that must be paid for each ticket the user purchases.
repeated SpecificPerTicketFee per_ticket_fee = 1;
// Fees and taxes that must be paid once per order, regardless of the number
// of tickets purchased.
repeated SpecificPerOrderFee per_order_fee = 2;
}
// A deposit that the user may be charged or have a hold on their credit card
// for.
message Deposit {
// Deposit amount.
Price deposit = 1;
// Minimum advance cancellation for the deposit.
int64 min_advance_cancellation_sec = 2;
// Defines how the deposit is determined from the availability.
PriceType deposit_type = 3;
}
// Slot specification
// An inventory slot
message Slot {
// ID of the merchant for the slot (required)
string merchant_id = 1;
// ID of the merchant Service (required)
string service_id = 2;
// Start time of the appointment slot in seconds of UTC time since Unix epoch.
// (required)
int64 start_sec = 3;
// Duration of the appointment slot (required)
int64 duration_sec = 4;
// Opaque tag that identifies the availability slot and matches the value
// provided in the availability feed (optional)
string availability_tag = 5;
// The set of resources that disambiguates the appointment slot, e.g. by
// indicating the staff member and room selected by the user (optional)
ResourceIds resources = 6;
// Indicates whether bookings of this slot will be confirmed
// synchronously or asynchronously. An UNSPECIFIED value will be interpreted
// as synchronous.
ConfirmationMode confirmation_mode = 7;
}
// User specification
// Personal information about the person making a booking
message UserInformation {
// Unique ID of the user to the partner, chosen by Reserve with Google.
// (required)
string user_id = 1;
// Given name of the user (maximum 40 characters) (required)
string given_name = 2;
// Family name of the user (maximum 40 characters) (required)
string family_name = 3;
// Address of the user (optional)
PostalAddress address = 4;
// Phone number of the user (required)
string telephone = 5;
// Email address of the user (required)
string email = 6;
}
// The postal address for a merchant.
message PostalAddress {
// The country, e.g. "USA". (required)
string country = 1;
// The locality/city, e.g. "Mountain View". (required)
string locality = 2;
// The region/state/province, e.g. "CA". (required)
string region = 3;
// The postal code, e.g. "94043". (required)
string postal_code = 4;
// The street address, e.g. "1600 Amphitheatre Pkwy". (required)
string street_address = 5;
}