Protocol Documentation

Table of Contents

Top

engine/common/v1/actions.proto

AvailableActions

Describes the availability of actions on a BookingDetails.

Field Type Label Description
cancel ActionAvailability   Describes the availability of the cancel action.
modify ActionAvailability   Describes the availability of the modify action.

ActionAvailability

Describes the means by which an action may be taken on a BookingDetails.

Name Number Description
ACTION_AVAILABILITY_UNKNOWN 0 It is unknown if the action is available. It might be available directly through the vendor.
ACTION_AVAILABILITY_UNAVAILABLE 1 The action is not available through the API. It is unknown whether it can be performed in another context, such as through the vendor or support.
ACTION_AVAILABILITY_AVAILABLE 2 The action is available through the API.
ACTION_AVAILABILITY_AVAILABLE_VIA_VENDOR 3 The action is available, but only through the service provider.
ACTION_AVAILABILITY_AVAILABLE_VIA_SUPPORT 4 The action is available, but only through customer support.

Top

engine/common/v1/amenities.proto

AmenityAvailability

Describes the condition of an amenity's inclusion on a Property, RoomDescription, OfferSummary, or BookingDetails.

Name Number Description
AMENITY_AVAILABILITY_UNKNOWN 0 The availability of an amenity cannot be confirmed.
AMENITY_AVAILABILITY_UNAVAILABLE 1 The amenity is confirmed to not be available.
AMENITY_AVAILABILITY_INCLUDED 2 The amenity is confirmed to be included.
AMENITY_AVAILABILITY_VIA_VENDOR 3 The amenity is not included, but may be purchased directly from the hotel, airline, car rental vendor, etc. For example, a seat upgrade or breakfast vouchers.

Top

engine/common/v1/conditions.proto

Condition

An individual condition to be applied to an interaction with a booked item. For example, to cancel, or extend a Lodging BookingDetails.

Field Type Label Description
before_timestamp string optional If present, this condition applies before and up to this ISO-8601-compliant timestamp. For example, Changing this flight is free before May 30th. This field may interact with Condition.after_timestamp. See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations
after_timestamp string optional If present, this condition applies on or after this ISO-8601-compliant timestamp. For example, Canceling this flight incurs a $75 fee after June 1st. This field may interact with Condition.before_timestamp and Condition.before_event. See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations
before_event ConditionEventType optional If present, this condition applies up until the described event occurs. For example, Cancelling this flight is free until departure.
penalty CurrencyValue   Optionally, any charge incurred as a result of the intended action within the constraints of Condition.before_timestamp, Condition.after_timestamp, and Condition.before_event. penalty may be absent if the penalty is unknown. A missing penalty does not imply that there is no penalty. If the penalty is known to be zero, penalty will be present with a value of 0.
is_allowed bool optional If false, the intended operation is not allowed.

Conditions

Conditions that describe the availability, penalty, and timing constraints on modification to a booked item.

Field Type Label Description
modify_conditions Condition repeated Conditions that apply to modification of a BookingDetails. If no modify_conditions exist, the BookingDetails may not be modified.
cancel_conditions Condition repeated Conditions that apply to cancellation of a BookingDetails. If no cancel_conditions exist, the BookingDetails may not be canceled.

ConditionEventType

Events that affect the availability of an action when a specific timestamp is not available.

Name Number Description
CONDITION_EVENT_TYPE_UNKNOWN 0  
CONDITION_EVENT_TYPE_DEPARTURE 1  
CONDITION_EVENT_TYPE_CHECKIN 2  

Top

engine/common/v1/currency.proto

CurrencyValue

A safe encoding of a monetary value and its paired currency code.

Field Type Label Description
currency_code string   The 3-character ISO-4217 alphabetic currency code. For example: USD See https://www.iso.org/iso-4217-currency-codes.html
value string   The non-localized decimal representation of the amount of currency represented by this object. For example, "123456.789".

Top

engine/common/v1/geo.proto

Distance

The distance between two geographic points.

Field Type Label Description
value double   The distance quantity.
unit DistanceUnit   The unit of distance measurement.

GeoPoint

A single geographic point, defined by latitude and longitude.

Field Type Label Description
latitude double   The center-point latitude.
longitude double   The center-point longitude.

GeoRadius

An perfect-circle area surrounding a single geographic point.

Field Type Label Description
point GeoPoint   The center point of the circle.
radius Distance   The length of the radius of the circle.

DistanceUnit

The unit type for a distance measurement.

Name Number Description
DISTANCE_UNIT_MILE 0 A mile in the imperial system of units.
DISTANCE_UNIT_KILOMETER 1 A kilometer in the international system of units (metric).

Top

engine/common/v1/loyalty.proto

LodgingLoyaltyProgramIdentifier

An identifier signifying a traveler's membership in a Loyalty Program. Loyalty Program Identifiers are provided by the administrator of that program. Not all OfferSummary will grant loyalty rewards.

Field Type Label Description
member_id string   The identifier provided to the travel by the program administrator.

Top

engine/common/v1/postal_address.proto

PostalAddress

Represents a Postal Address.

Field Type Label Description
recipients string repeated Optionally, any individual recipients. For example, "Alexander Hamilton", "Aaron Burr" May be empty.
organization string optional Optionally, any organization or company as a recipient. For example, "Engine".
address_line string repeated Optionally, any address lines, in order as they'd appear on an envelope. For example, "233 S Wacker Dr", "108th Floor". May be empty.
administrative_area string optional Optionally, the State, province, prefecture, oblast, or area. For example, "Texas"
locality string optional Optionally, the City, or Post Town For example, "Austin"
postal_code string optional Optionally, the postal code, if one exists, for the address. For example, "78757".
country_code string optional Optionally, the ISO 3166-1 alpha-2 country code. For example, "US". See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 See https://www.iso.org/iso-3166-country-codes.html

Top

engine/common/v1/price.proto

PerUnitPrice

A price representing the cost of a single unit in a multi-unit breakdown. For example, price per night.

Field Type Label Description
key string   A key to distinguish which unit is represented by this price. For example, which date, or which passenger.
unit string   The type of unit. For example, "night" or "person".
price Price   The cost for this unit.

Price

The details of the cost of an item or service.

Field Type Label Description
sub_total CurrencyValue   The sum total for the booking excluding taxes and fees. The subtotal includes all Price.line_items.
total CurrencyValue   The full liability to purchase the item. This is not necessarily the amount due at time of booking due to discounts, incentives, or postpaid items.
taxes Surcharge repeated Any taxes to be collected at time of payment.
fees Surcharge repeated Any fees applied to the item or service.
base CurrencyValue   The cost of the main item or service in the booking, less upgrades or additional services, fees, and taxes. The base is equivalent to: Price.sub_total - sum(Price.line_items)
line_items PriceLineItem repeated Additional upgrades to an item or service added during the shopping experience. Line items are represented in the Price.sub_total.
taxes_and_fees_total CurrencyValue   The sum of all individual Price.taxes and Price.fees.
strike CurrencyValue   A representative market price for the item or service without any discounts applied.
total_due_now CurrencyValue   The total amount due at time of booking.
total_due_later CurrencyValue   The total amount due at the time of the travel event.

PriceLineItem

A individual service or upgrade added to an item during the shopping experience.

Field Type Label Description
description string   A textual description of the individual charge.
price CurrencyValue   The price of this line item.
group string optional Optionally, an identifier to group line items for visual display. For example, "Extras" or "Loyalty Benefits".

PriceWithPerUnit

The total price, along with a breakdown by a given unit. For example, the total stay cost and the per-night cost.

Field Type Label Description
price Price   The total price for the item.
per_unit_price PerUnitPrice repeated The total price broken into per-unit costs

Surcharge

An additional charge, fee, or tax.

Field Type Label Description
description string   A textual description of the purpose of the Surcharge.
amount CurrencyValue   The amount levied.
type SurchargeType   The type of surcharge

SurchargeType

A programmatic classification of types of surcharges that could be levied.

Name Number Description
SURCHARGE_TYPE_PREPAID_FEE 0 A fee due at time of booking.
SURCHARGE_TYPE_POSTPAID_FEE 1 A fee due at time of travel.
SURCHARGE_TYPE_TAX 2 Taxes due at time of booking.

Top

engine/common/v1/refund.proto

Refund

Details that describe any refund due or granted related to a modification or cancellation of a BookingDetails.

Field Type Label Description
amount CurrencyValue   The full amount of the refund.

Top

engine/common/v1/sales_channel.proto

SalesChannel

Describes the source of client

Name Number Description
SALES_CHANNEL_UNKNOWN 0 The sales channel cannot be determined.
SALES_CHANNEL_MOBILE_NATIVE 1 The customer is shopping via a mobile application.
SALES_CHANNEL_MOBILE_WEB 2 The customer is shopping via a mobile web browser.
SALES_CHANNEL_WEB 3 The customer is shopping via a web browser on a desktop or laptop computer.

Top

engine/common/v1/traveler.proto

AnonymousAdult

An adult traveler whose personal details have not yet been collected.

AnonymousChild

A child traveler whose personal details have not yet been collected. A child's age is necessary to retrieve the correct prices. Failure to provide an accurate age may result in loss of bookings or refusal to provide service to the traveler.

Field Type Label Description
age int32   The child's age on the date of travel. If the child's birthday is during travel, use the age they will be at the end of travel.
birthdate string   An ISO-8601-compliant date representing the child's birthdate. See https://en.wikipedia.org/wiki/ISO_8601#Dates

AnonymousTraveler

A traveler whose personal details have not yet been collected.

Field Type Label Description
adult AnonymousAdult    
child AnonymousChild    

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double   double double float float64 double float Float
float   float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool   bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)

Back to top

Copyright © 2025 HotelEngine, Inc., d/b/a Engine
Documentation generated: August 06, 2025
Version: 2.0.0-pre.5