Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Omni, Powered by Engine Lodging Booking Service API
description: Definitions for the Omni travel API.
version: 2.4.0
contact:
name: Omni API Support
url: https://omni.engine.com/
license:
name: Apache License Version 2.0
url: https://github.com/engine-public/engine-partner-api/blob/main/LICENSE
servers:
- url: https://partner-api.engine.com
tags:
- name: LodgingBookingService
paths:
/book/v1/lodging/booking:
post:
summary: Retrieve bookings given the provided Booking IDs.
description: In case of error, the status will contain a [GetBookingsError] within the [Status.details] field.
operationId: LodgingBookingService_GetBookings
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetBookingsResponse'
'400':
description: Error details for gRPC Status of INVALID_ARGUMENT(3).
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetBookingsError'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
tags:
- LodgingBookingService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1GetBookingsRequest'
description: A request to retrieve one or more [BookingDetails].
required: true
put:
summary: Purchase and reserve an Offer.
description: In case of error, the status will contain a [BookError] within the [Status.details] field.
operationId: LodgingBookingService_Book
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1BookResponse'
'400':
description: Error details for gRPC Status of INVALID_ARGUMENT(3).
content:
application/json:
schema:
$ref: '#/components/schemas/v1BookError'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
tags:
- LodgingBookingService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1BookRequest'
description: A request to purchase and reserve an [OfferSummary].
required: true
/book/v1/lodging/booking/generate-folio:
post:
summary: Generate a folio.
description: In case of error, the status will contain a [GenerateFolioError] within the [Status.details] field.
operationId: LodgingBookingService_GenerateFolio
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/apiHttpBody'
'400':
description: Error details for gRPC Status of FAILED_PRECONDITION(9).
content:
application/json:
schema:
$ref: '#/components/schemas/v1GenerateFolioError'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
tags:
- LodgingBookingService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1GenerateFolioRequest'
description: Generates a folio HTTP response for a Booking.
required: true
/book/v1/lodging/booking/preview-cancellation:
post:
summary: Get the availability, means, and expected refund for a booking cancellation.
description: In case of error, the status will contain a [PreviewCancellationError] within the [Status.details] field.
operationId: LodgingBookingService_PreviewCancellation
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1PreviewCancellationResponse'
'400':
description: Error details for gRPC Status of INVALID_ARGUMENT(3).
content:
application/json:
schema:
$ref: '#/components/schemas/v1PreviewCancellationError'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
tags:
- LodgingBookingService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1PreviewCancellationRequest'
description: Requests the expected result of a cancellation.
required: true
/book/v1/lodging/booking/submit-cancellation:
post:
summary: Attempt to cancel a booking.
description: In case of error, the status will contain a [SubmitCancellationError] within the [Status.details] field.
operationId: LodgingBookingService_SubmitCancellation
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1SubmitCancellationResponse'
'400':
description: Error details for gRPC Status of INVALID_ARGUMENT(3).
content:
application/json:
schema:
$ref: '#/components/schemas/v1SubmitCancellationError'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
tags:
- LodgingBookingService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1SubmitCancellationRequest'
description: Requests cancellation of a Booking.
required: true
/book/v1/lodging/confirm-offer:
post:
summary: Confirm the availability, pricing, and details of an Offer prior to booking.
description: In case of error, the status will contain a [ConfirmOfferError] within the [Status.details] field.
operationId: LodgingBookingService_ConfirmOffer
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1ConfirmOfferResponse'
'400':
description: Error details for gRPC Status of INVALID_ARGUMENT(3).
content:
application/json:
schema:
$ref: '#/components/schemas/v1ConfirmOfferError'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
tags:
- LodgingBookingService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1ConfirmOfferRequest'
description: A request to confirm final pricing and availability of an [OfferSummary].
required: true
components:
schemas:
v1PreviewCancellationError:
type: object
properties:
invalidState:
$ref: '#/components/schemas/v1InvalidStateError'
description: 'Defined when the operation returns with a status of INVALID_ARGUMENT and the booking associated
with the given booking ID is not in a valid state, e.g. It has not been booked, or is
already cancelled.'
description: Error details of a failed [LodgingBookingService.PreviewCancellation] call.
title: Book_Lodging_Service_PreviewCancellationError_v1
v1ConfirmOfferRequest:
type: object
properties:
continuationToken:
type: string
description: A `continuation_token` from [LodgingShoppingService.FindBestOffers], [LodgingShoppingService.FindBestOffersStreaming], or [LodgingShoppingService.FindAvailability].
currencyCode:
type: string
title: 'The currency code for this request.
This field specifies the currency in which the requester expects to see prices.
It must adhere to the ISO 4217 three-character alphabetic currency code ("USD", "EUR", etc.).
https://www.iso.org/iso-4217-currency-codes.html'
description: A request to confirm final pricing and availability of an [OfferSummary].
title: Book_Lodging_Service_ConfirmOfferRequest_v1
v1BookResponse:
type: object
properties:
details:
$ref: '#/components/schemas/v1BookingDetails'
description: The recorded details of the [BookingDetails] and [ReservationDetails].
description: The result of an attempt to purchase and reserve an [OfferSummary].
title: Book_Lodging_Service_BookResponse_v1
v1SubmitCancellationError:
type: object
properties:
actionNotAvailable:
$ref: '#/components/schemas/v1ActionNotAvailableError'
description: The cancellation action is not available for the booking.
cannotCancel:
$ref: '#/components/schemas/v1CannotCancelError'
description: 'Defined when the operation returns with a status of INVALID_ARGUMENT and the
requested booking is not cancellable.'
invalidState:
$ref: '#/components/schemas/v1InvalidStateError'
description: 'Defined when the operation returns with a status of INVALID_ARGUMENT and the booking associated
with the given booking ID is not in a valid state, e.g. It has not been booked, or is
already cancelled.'
description: Error information returned in the error details of failed SubmitCancellation calls.
title: Book_Lodging_Service_SubmitCancellationError_v1
v1ReservationDetails:
type: object
properties:
confirmationNumbers:
type: array
items:
type: string
description: 'The confirmation numbers provided by the [Property] after a successful reservation.
Confirmation numbers may not be available immediately after booking.
The quantity of confirmation numbers may vary by the [Property] booked.'
createdAt:
type: string
title: 'An ISO-8601-compliant date and time at which the [ReservationDetails] was booked.
See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations'
quote:
$ref: '#/components/schemas/v1Quote'
description: The details of the [Quote] that was purchased.
property:
$ref: '#/components/schemas/lodgingProperty'
description: The details of the [Property] at the time of the reservation.
appliedPaymentInfo:
$ref: '#/components/schemas/v1AppliedPaymentInfo'
description: The details of the [AppliedPaymentInfo] for the reservation.
description: Details of the Reservation made with the [Property].
title: Book_Lodging_ReservationDetails_v1
v1OfferSummary:
type: object
properties:
propertyId:
type: string
description: The Engine identifier for the Property to which this Offer belongs.
description:
type: string
description: A textual description of the Offer.
price:
$ref: '#/components/schemas/v1PriceWithPerUnit'
description: 'The pricing details for the Offer.
This price indicates the amount owed to Engine at the time of booking.
Refer to [OfferSummary.sell_type] for details on how the offer may be priced to the customer.'
offerAmenities:
$ref: '#/components/schemas/v1OfferAmenities'
description: 'Amenities that may only apply to this Offer.
For example, some Offers may include parking.'
conditions:
$ref: '#/components/schemas/v1Conditions'
description: The conditions covering refundability and cancellation.
isLoyaltyEligible:
type: boolean
description: If true, this Offer may earn loyalty points.
isLoyaltyMembershipIdRequired:
type: boolean
description: If true, this offer requires a loyalty membership id to book.
rateData:
$ref: '#/components/schemas/v1RateData'
description: Optionally, if this offer represents a negotiated rate specifically configured for your credential, the details of that rate will be included here.
sellType:
$ref: '#/components/schemas/v1SellType'
description: 'The sell type for this offer.
Defines how the seller is compensated and the pricing guidelines for this offer.
See [SellType] for details on available model types and their pricing rules.'
description: A summary of the attributes available to a specific Offer.
title: Shop_Lodging_OfferSummary_v1
v1OfferNoLongerAvailableError:
type: object
description: An error indicating that the [OfferSummary] is no longer available. This is likely due to the [OfferSummary] being sold out.
title: Book_Common_Service_OfferNoLongerAvailableError_v1
v1EngineDirectBill:
type: object
description: 'Indicates payment via Engine Direct Bill.
If an Engine Direct Bill account has not been established, an [InvalidPaymentError] error will be returned.'
title: Common_EngineDirectBill_v1
v1GeoPoint:
type: object
properties:
latitude:
type: number
format: double
description: The center-point latitude.
longitude:
type: number
format: double
description: The center-point longitude.
description: A single geographic point, defined by latitude and longitude.
title: Common_GeoPoint_v1
v1LodgingLoyaltyProgramIdentifier:
type: object
properties:
memberId:
type: string
description: The identifier provided to the travel by the program administrator.
description: '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.'
title: Common_LodgingLoyaltyProgramIdentifier_v1
v1GetBookingsError:
type: object
properties:
errors:
type: array
items:
type: object
$ref: '#/components/schemas/v1GetBookingError'
description: If available, the individual [BookingDetails] that could not be retrieved, in no particular order.
description: Error details of a failed [LodgingBookingService.GetBookings] call.
title: Book_Lodging_Service_GetBookingsError_v1
v1NetModel:
type: object
description: '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.'
title: Common_NetModel_v1
v1ActionAvailability:
type: string
enum:
- ACTION_AVAILABILITY_UNKNOWN
- ACTION_AVAILABILITY_UNAVAILABLE
- ACTION_AVAILABILITY_AVAILABLE
- ACTION_AVAILABILITY_AVAILABLE_VIA_VENDOR
- ACTION_AVAILABILITY_AVAILABLE_VIA_SUPPORT
default: ACTION_AVAILABILITY_UNKNOWN
description: "Describes the means by which an action may be taken on a [BookingDetails].\n\n - ACTION_AVAILABILITY_UNKNOWN: It is unknown if the action is available. It might be available directly through the vendor.\n - ACTION_AVAILABILITY_UNAVAILABLE: 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.\n - ACTION_AVAILABILITY_AVAILABLE: The action is available through the API.\n - ACTION_AVAILABILITY_AVAILABLE_VIA_VENDOR: The action is available, but only through the service provider.\n - ACTION_AVAILABILITY_AVAILABLE_VIA_SUPPORT: The action is available, but only through customer support."
title: Common_ActionAvailability_v1
v1ConfirmOfferResponse:
type: object
properties:
continuationToken:
type: string
title: 'An opaque token that may be used to book the stay via [LodgingBookingService.Book].
See [LodgingBookingService.ConfirmOffer]'
quote:
$ref: '#/components/schemas/v1Quote'
description: The full details of the [OfferSummary], [RoomDescription], Dates of Travel, and any notices required for display during the confirmation process.
description: The result of a price and availability check.
title: Book_Lodging_Service_ConfirmOfferRequest_v1
v1AppliedPaymentInfo:
type: object
properties:
engineDirectBill:
$ref: '#/components/schemas/v1AppliedEngineDirectBill'
card:
$ref: '#/components/schemas/v1AppliedCardPayment'
description: Information about the form of payment used in a request.
title: Book_Common_AppliedPaymentInfo_v1
v1RoomGuests:
type: object
properties:
primaryGuest:
$ref: '#/components/schemas/v1GuestWithLoyalty'
title: The primary guest of a room
additionalGuests:
type: array
items:
type: object
$ref: '#/components/schemas/v1Guest'
description: 'Any additional names you wish to be able to check-in to the room without the [RoomGuests.primary_guest] present.
Not all Properties allow additional guests to check-in.
The primary guest should not be included in the `additional_guests` field.'
description: Details of the guests staying within a single room during the stay.
title: Book_Lodging_RoomGuests_v1
v1Surcharge:
type: object
properties:
description:
type: string
description: A textual description of the purpose of the Surcharge.
amount:
$ref: '#/components/schemas/v1CurrencyValue'
description: The amount levied.
type:
$ref: '#/components/schemas/v1SurchargeType'
title: The type of surcharge
description: An additional charge, fee, or tax.
title: Common_Surcharge_v1
v1BookingMetadata:
type: object
properties:
key:
type: string
title: 'A textual key to represent the purpose of the metadata, for example, "Contract ID".
Keys must be unique within a [BookingDetails].
Maximum length: 40 characters'
maxLength: 40.0
value:
type: string
title: 'A textual value.
Maximum length: 100 characters'
maxLength: 100.0
external:
type: boolean
description: 'If true, this Metadata entry will be included on invoices and reports.
If false, this entry will only be available via direct API access.'
description: 'Custom Metadata attached to a [BookingDetails].
Metadata values allow an Omni customer to carry a small amount of context on a [BookingDetails] for their own use.'
title: Book_Lodging_BookingMetadata_v1
v1SubmitCancellationResponse:
type: object
properties:
details:
$ref: '#/components/schemas/v1CancellationDetails'
description: The timestamp and refund details.
description: Returns the result of a requested cancellation.
title: Book_Lodging_Service_SubmitCancellationResponse_v1
v1PriceLineItem:
type: object
properties:
description:
type: string
description: A textual description of the individual charge.
price:
$ref: '#/components/schemas/v1CurrencyValue'
description: The price of this line item.
group:
type: string
description: 'Optionally, an identifier to group line items for visual display.
For example, "Extras" or "Loyalty Benefits".'
description: A individual service or upgrade added to an item during the shopping experience.
title: Common_PriceLineItem_v1
v1PostalAddress:
type: object
properties:
recipients:
type: array
items:
type: string
description: 'Optionally, any individual recipients.
For example, "Alexander Hamilton", "Aaron Burr"
May be empty.'
organization:
type: string
description: 'Optionally, any organization or company as a recipient.
For example, "Engine".'
addressLine:
type: array
items:
type: string
description: 'Optionally, any address lines, in order as they''d appear on an envelope.
For example, "233 S Wacker Dr", "108th Floor".
May be empty.'
administrativeArea:
type: string
title: 'Optionally, the State, province, prefecture, oblast, or area.
For example, "Texas"'
locality:
type: string
title: 'Optionally, the City, or Post Town
For example, "Austin"'
postalCode:
type: string
description: 'Optionally, the postal code, if one exists, for the address.
For example, "78757".'
countryCode:
type: string
title: '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'
description: Represents a Postal Address.
title: Common_PostalAddress_v1
lodgingExternalCatalogIdentifierList:
type: object
properties:
identifiers:
type: array
items:
type: string
description: 'Supplier property identifiers for the associated catalog key.
May contain multiple identifiers when more than one external record is mapped to the Engine record.'
description: A list of external catalog identifiers for a single catalog key.
title: Content_ExternalCatalogIdentifierList_v1
v1LodgingBookingStatusCode:
type: string
enum:
- LODGING_BOOKING_STATUS_UNSPECIFIED
- LODGING_BOOKING_STATUS_PENDING
- LODGING_BOOKING_STATUS_CONFIRMED
- LODGING_BOOKING_STATUS_CANCELED
default: LODGING_BOOKING_STATUS_UNSPECIFIED
description: "A value representing the state of a [BookingDetails].\n\n - LODGING_BOOKING_STATUS_PENDING: The Booking has been submitted, but has not yet been confirmed.\n - LODGING_BOOKING_STATUS_CONFIRMED: The Booking has been confirmed.\n - LODGING_BOOKING_STATUS_CANCELED: The Booking has been canceled and is no longer active."
title: Book_Lodging_LodgingBookingStatusCode_v1
v1RoomDescription:
type: object
properties:
title:
type: string
description: 'The title of a room.
For example, "Standard 1 King Bed", or "Suite 1 King Bed", "The Canary Suite".'
description:
type: string
title: 'A textual marketing description of the room.
For example, "SKYLINE VIEW KING ROOM -CITY OR RIVER VIEW 1 KING -430 SQF"'
beds:
type: array
items:
type: object
$ref: '#/components/schemas/v1Bedding'
description: The available bedding for the room.
photos:
type: array
items:
type: string
description: URIs to photos of this room.
amenities:
type: array
items:
type: object
$ref: '#/components/schemas/lodgingRoomAmenity'
description: A list of amenities that are available in the room.
description: Generalized details of the room to which an Offer applies.
title: Shop_Lodging_RoomDescription_v1
v1Quote:
type: object
properties:
checkInDate:
type: string
title: 'An ISO-8601-compliant date on which the stay begins.
See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates'
checkOutDate:
type: string
title: 'An ISO-8601-compliant date on which the stay ends.
See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates'
offerSummary:
$ref: '#/components/schemas/v1OfferSummary'
description: The details of the [OfferSummary] to be Booked.
roomCount:
type: integer
format: int32
description: The number of rooms to be Booked.
roomDescription:
$ref: '#/components/schemas/v1RoomDescription'
description: The details of the [RoomDescription] to be booked.
availableActions:
$ref: '#/components/schemas/v1AvailableActions'
description: 'Optionally, the actions (such as cancellation) that are available for the [BookingDetails] if they are known.
Not every action will be available through the API for every reservation.
Some may be available but the availability is not known at the point of the [LodgingBookingService.ConfirmOffer] or the [LodgingBookingService.Book] request.'
description: The full details of the item to be Booked.
title: Book_Lodging_Quote_v1
v1Conditions:
type: object
properties:
modifyConditions:
type: array
items:
type: object
$ref: '#/components/schemas/v1Condition'
description: 'Conditions that apply to modification of a [BookingDetails].
If no modify_conditions exist, the [BookingDetails] may not be modified.'
cancelConditions:
type: array
items:
type: object
$ref: '#/components/schemas/v1Condition'
description: 'Conditions that apply to cancellation of a [BookingDetails].
If no cancel_conditions exist, the [BookingDetails] may not be canceled.'
description: Conditions that describe the availability, penalty, and timing constraints on modification to a booked item.
title: Common_Conditions_v1
lodgingProperty:
type: object
properties:
id:
type: string
description: The [Engine] identifier for this [Property].
name:
type: string
description: The full name of this [Property].
physicalAddress:
$ref: '#/components/schemas/v1PostalAddress'
description: 'The physical address of this [Property].
This may differ from the mailing, billing, or other administrative addresses.'
coordinates:
$ref: '#/components/schemas/v1GeoPoint'
description: The geographic location of this [Property].
heroImageUri:
type: string
description: If available, A URI to the image to use as the primary image to identify this [Property].
description:
type: string
description: If available, a brief textual description of this [Property].
phoneNumber:
type: string
title: 'If available, an E.164-compliant primary phone number for this [Property].
See https://en.wikipedia.org/wiki/E.164'
emails:
type: array
items:
type: object
$ref: '#/components/schemas/v1ContactEmail'
description: 'Contact email addresses for this property.
May include general contact, billing, or reservation emails.'
starRating:
type: string
title: 'Star rating for this property.
Represents the official star rating classification system.
See https://en.wikipedia.org/wiki/Hotel_rating
Examples: "4", "5", "3.5"'
amenities:
type: array
items:
type: object
$ref: '#/components/schemas/lodgingPropertyAmenity'
title: 'Property amenities for this [Property].
List of amenity names describing features and services available to guests.
Examples: "Free WiFi", "Pool", "Fitness Center", "Free Breakfast"'
mediaItems:
type: array
items:
type: object
$ref: '#/components/schemas/v1MediaItem'
description: 'Media items for property gallery.
Collection of media URIs for detailed property viewing and marketing.'
catalog:
$ref: '#/components/schemas/lodgingExternalCatalogIdentifiers'
description: 'External catalog identifiers for this property.
Used for integration with external booking systems.'
checkInTime:
type: string
description: Check-in time in local time HH:MM 24-hour format (e.g., "15:00") for the [Property].
checkOutTime:
type: string
description: Check-out time in local time HH:MM 24-hour format (e.g., "11:00") for the [Property].
loyaltyRewardsProgram:
$ref: '#/components/schemas/v1LoyaltyRewardsProgram'
description: The loyalty rewards program associated with the [Property].
timeZone:
type: string
title: 'The time zone for the [Property] in the IANA format.
See https://www.iana.org/time-zones
Examples: "America/Denver", "Atlantic/Madeira"'
description: An individual Lodging location identified by [Engine].
title: Content_Property_v1
v1PerUnitPrice:
type: object
properties:
key:
type: string
description: 'A key to distinguish which unit is represented by this price.
For example, which date, or which passenger.'
unit:
type: string
description: 'The type of unit.
For example, "night" or "person".'
price:
$ref: '#/components/schemas/v1Price'
description: The cost for this unit.
description: 'A price representing the cost of a single unit in a multi-unit breakdown.
For example, price per night.'
title: Common_PerUnitPrice_v1
v1Guest:
type: object
properties:
familyName:
type: string
description: The guest's family name or last name.
givenName:
type: string
description: The guest's given name or first name.
isAdult:
type: boolean
description: True if the guest is an adult.
description: A traveler for the stay.
title: Book_Lodging_Guest_v1
v1CancellationDetails:
type: object
properties:
canceledAt:
type: string
title: 'An ISO-8601-compliant date and time at which the [BookingDetails] was canceled.
See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations'
refund:
$ref: '#/components/schemas/v1Refund'
description: The details of the Refund granted when canceled.
description: Details of the cancellation of a [BookingDetails].
title: Book_Lodging_CancellationDetails_v1
v1AvailableActions:
type: object
properties:
cancel:
$ref: '#/components/schemas/v1ActionAvailability'
description: Describes the availability of the cancel action.
modify:
$ref: '#/components/schemas/v1ActionAvailability'
description: Describes the availability of the modify
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hotel-engine/refs/heads/main/openapi/hotel-engine-lodgingbookingservice-api-openapi.yml