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/contact.proto

ContactEmail

Contact email information.

Field Type Label Description
email_address string   The email address.
email_type EmailType optional Optional type of email contact.

EmailType

Describes the type of an email contact.

Name Number Description
EMAIL_TYPE_UNSPECIFIED 0 Unspecified email type.
EMAIL_TYPE_GENERAL 1 General contact email.
EMAIL_TYPE_BILLING 2 Billing-related email.
EMAIL_TYPE_RESERVATIONS 3 Reservations and booking email.
EMAIL_TYPE_SUPPORT 4 Customer support email.

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/engine_direct_bill.proto

EngineDirectBill

Indicates payment via Engine Direct Bill. If an Engine Direct Bill account has not been established, an InvalidPaymentError error will be returned.

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/image.proto

Image

Represents an Image with optional metadata.

Field Type Label Description
uri string   The URI of the Image. For example, "https://example.com/image.jpg"

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.

LoyaltyRewardsProgram

Represents a single loyalty rewards program.

Field Type Label Description
name string   Name of the loyalty reward program.

Top

engine/common/v1/media.proto

MediaItem

A media item for visual or marketing context.

Field Type Label Description
image Image   An Image this media item represents
description string optional A description of this media item Example: "A large restaurant"
tags string repeated Tags categorizing the content of this media item Example: ["outdoor", "pool"]

Top

engine/common/v1/payment_card.proto

PaymentCard

The payment card that will be charged.

Field Type Label Description
number string   The payment card number as a string of digits without any separators or whitespace.
security_code string   The card security code, such as CVV or CVC.
expiration_month string   The number representing the card’s expiration month (01 through 12). Leading zeroes should be included.
expiration_year string   Four-digit number representing the card’s expiration year.
billing_address PostalAddress   The billing address associated with the payment card being charged.

Top

engine/common/v1/payment_info.proto

PaymentInfo

The payment method used in a request. If omitted, the default payment method configured for the caller will be used. If no default payment method is configured, an InvalidPaymentError error will be returned.

Field Type Label Description
engine_direct_bill EngineDirectBill    
payment_card PaymentCard    

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 Deprecated. Any taxes to be collected at time of payment. This field is deprecated. Use [Price.taxes_and_fees] instead.
fees Surcharge repeated Deprecated. Any fees applied to the item or service. This field is deprecated. Use [Price.taxes_and_fees] instead.
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.
taxes_and_fees Surcharge repeated Any taxes and fees to be collected at time of payment. This includes all taxes and fees due at time of booking.

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/sell_type.proto

CommissionableModel

Details for a commissionable pricing model. Under this model, offers must be sold at the exact price quoted by Engine without markup. The seller receives a fixed commission amount for each sale. This model does not override your agreement with Engine. Refer to your agreement or contact your Engine sales support team for questions.

Field Type Label Description
commission_value CurrencyValue   The commission amount the seller will receive for selling this offer.

FixedModel

Details for a fixed pricing model. Under this model, offers must be sold at the exact price quoted by Engine without markup. The seller does not receive commission for offers indicated with this pricing model. Compensation terms are defined exclusively by the seller's agreement with Engine. Refer to your agreement or contact your Engine sales support team for questions.

NetModel

Details for a net pricing model. Under this model, offers are provided at a net price which the seller is expected to mark up. The seller's earnings consist of the margin between the net price and the final price charged to the customer. The markup amount and strategy are determined by the seller within the terms of their agreement. Net rates can be sold at any price no lower than OfferSummary.price.price.total and no higher than OfferSummary.price.price.strike. This model does not override your agreement with Engine. Refer to your agreement or contact your Engine sales support team for questions.

SellType

The sell type of an offer. Defines seller compensation and pricing guidelines for this offer. The type determines whether the seller earns through commission, markup margin, or other contractual arrangements.

Field Type Label Description
commissionable CommissionableModel   Indicates this offer uses a commissionable sell type. Offers with this type must be sold at the exact price quoted by Engine. The seller earns a commission specified in CommissionableModel. See CommissionableModel for details.
net NetModel   Indicates this offer uses a net sell type. Offers with this type are expected to be marked up by the seller. The seller earns the margin between the net price and the marked-up price. See NetModel for details.
fixed FixedModel   Indicates this offer uses a fixed sell type. Offers with this type must be sold at the exact price quoted by Engine. Compensation terms are defined exclusively by the seller's agreement with Engine. See FixedModel for details.

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)