ReferenceReservations

reservations query

Retrieves information about a single property's reservations. Information is returned at the property level, not the unit level.

  • Retrieve (filter) reservations by checkout date; they are returned in chronological order (sorted by creationDateTime, earliest to latest).
  • Retrieve reservations by last updated date; this is helpful in identifying modified reservations (by comparing a reservation's creationDataTime and lastUpdatedDateTime).
  • Retrieve specific reservations by specifying the reservationIds filter.
  • Only reservations for properties that were onboarded to Expedia sites are retrieved. Retrieving reservations for Vrbo properties is not supported at this time.
  • Up to 10,000 reservations can be retrieved using this query.
Note: The reservations query is nested under the property query, which provides access to other capabilities, such as property status and promotions. However, you must be granted access to each capability before you can code to it. Contact your Technical Relationship Manager if you are interested in more than reservations.

Syntax

1query {
2 property(
3 id: String!,
4 idSource: IdSource
5 )
6 {
7 reservations(
9 pageSize: Int!,
10 after: String
12 }
13}

Example

The GraphQL explorer is provided below. Use this interactive explorer to run the sample query, which enables you to retrieve the following:

  • All reservations on the property that have checkout dates within the specified window in chronological order (sorted by creationDateTime, earliest to latest)
  • The rateIds type provides IDs to use when mapping the rate plan IDs. When idSource is set to SUPPLIER, the id field returns the same value as returned by the existing booking APIs. (For Hotel Collect properties, the A- prefix is no longer added to the source value and the A suffix is no longer appended to the rate ID as was done by the booking APIs.)
  • The specified checkout window ({ from: "2021-08-05", to: "2021-08-05" }) returns data for an Expedia Collect reservation. To see data for a Hotel Collect reservation, change the checkOutDate argument to { from: "2021-08-06", to: "2021-08-06" }.

Note that you can also filter retrieved reservations by last updated date or reservation ID, though this is not shown in this example.

The GraphQL explorer will help you get comfortable with the GraphQL:

  • For each query, a test property ID is passed into the explorer; its test data is returned.
  • Click Run Query to execute the query in the explorer on the page. You can modify the query to retrieve the desired fields, and the explorer provides a list of fields when you start typing.
  • Click API Explorer to launch the full explorer in another tab/window, which provides syntax highlighting, schema introspection, real-time error highlighting, and auto-completion, among other things.

Response

Arguments

NameDescription

id

Required.

Expedia ID (EID) or supplier ID (external ID in the partner's system) of the property.

If specifying the supplier ID for a Vrbo property, specify the ID in this format: systemId/advertiserId/listingExternalId.

  • For direct PM integrations, the value of systemId is “PM”.
  • For PMS integrations, this value represents the PMS originating the request.

If you are unsure of your system ID, contact your Engagement Manager or Technical Relationship Manager.

Type: String

idSource

Source system of the ID. EXPEDIA is the default value.

Type: IdSource

Types


Name
Type
Boolean
Boolean

The Boolean scalar type represents true or false.

BusinessModel
Enum

Entity that collects payment.

NameDescription
EXPEDIA_COLLECT

Expedia collects payment.

HOTEL_COLLECT

Property collects payment.

CheckOutDateFilter
InputObject

Checkout date window for which to filter reservations. You can query for reservations up to 465 days in the past and up to 500 days in the future.

FieldDescription
fromNot nullable.

Date that defines the start of the checkout date window (format: YYYY-MM-DD).

Type: LocalDate
toNot nullable.

Date that defines the end of the checkout date window (format: YYYY-MM-DD).

Type: LocalDate
EmailAddress
EmailAddress

A field whose value conforms to the standard internet email address format as specified in HTML Spec.

ExpediaSupplierAmount
Object
FieldDescription
currencyCodeNot nullable.

Currency in which the amount is shown.

Type: String
ratesNot nullable.

Nightly rates for the reservation.

Type: Array of non nullable SupplierRate
rateTypeNot nullable.

Rate type: NET for Expedia Collect or SELL for Hotel Collect.

Type: RateType
totalNot nullable.

Total rates for the reservation.

Type: SupplierTotal
Float
Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Guest
Object
FieldDescription
emailAddress

Guest's email address.

Type: EmailAddress
firstNameNot nullable.

Guest's first (given) name.

Type: String
lastNameNot nullable.

Guest's last name (surname).

Type: String
loyaltyTier

The traveler's Expedia Group VIP Access loyalty tier. These reservations often include value add promotions (VAPs), therefore it is important to associate this field and reservation:valueAddedPromotions in your systems so that end-users can properly identify loyal travelers and loyalty perks that the traveler is expecting. Values include MEMBER, VIP, PREMIUMVIP, and null. You must include this field to complete certification.

Type: String
phoneNumbers

The phone numbers of the guest.

Type: Array of non nullable GuestContactPhoneNumber
supplierLoyaltyPlanInfo

Details about the frequent traveler reward program. This field identifies if the traveler is a member of the supplier's loyalty program to ensure the supplier is able to greet the guest accordingly and award loyalty points as needed.

Type: SupplierLoyaltyPlanInfo
travelPurpose

Purpose of the guest's reservation.

Type: TravelPurpose
GuestContactPhoneNumber
Object

Guest phone number.

FieldDescription
areaCodeNot nullable.

Area code (three digits).

Type: String
countryCodeNot nullable.

Country code (two digits).

Type: String
numberNot nullable.

Phone number (seven digits, no hyphen).

Type: String
ID
ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

IdNode
Object

Known IDs in the source system.

FieldDescription
id

ID in the source system.

Type: ID
idSourceNot nullable.

Source of the ID.

Type: IdSource
IdNodeInput
InputObject

Reservation ID and its source.

FieldDescription
idNot nullable.

ID in the source system.

Type: ID
idSourceNot nullable.

Source of the ID.

Type: ReservationIdSource
IdSource
Enum

Source of a given ID.

NameDescription
EXPEDIA

Expedia is the source of the ID.

SUPPLIER

Connectivity provider or lodging partner is the source of the ID. This value is not supported for use in promotions.

VRBO

Unsupported.

Int
Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

InvalidScenario
Object

Reason and description of the scenario that makes the reservation ineligible for reconciliation.

FieldDescription
reasonNot nullable.

Description of why the reservation is ineligible for reconciliation.

Type: String
scenarioNot nullable.

Reason why the reservation cannot be reconciled. Values include the following:

  • GUEST_REQUESTED_CANCEL - Traveler cancelled the reservation
  • NO_SHOW - Traveler was a no-show
  • MODIFY_DATES_AMOUNTS - There was a difference in the booking price when the lodging partner charged the traveler (for example, because an extra night was added at the time of stay)
Type: String
LastUpdatedDateTimeFilter
InputObject

Date and time window when a reservation was last updated.

FieldDescription
fromNot nullable.

Starting date and time when the reservation was last updated (format: YYYY-MM-DDTHH:mm:ssTZD, TZD is a time zone designator in the form +/-hh:mm).

Type: ZoneDateTime
toNot nullable.

Ending date and time when the reservation was last updated (format: YYYY-MM-DDTHH:mm:ssTZD, TZD is a time zone designator in the form +/-hh:mm).

Type: ZoneDateTime
LocalDate
LocalDate

A type representing a date in ISO 8601 format: YYYY-MM-DD (such as 2007-12-03).

PageInfo
Object

Information about the current page of results.

FieldDescription
endCursor

Value of the cursor of the last result on the current page.

Type: String
hasNextPageNot nullable.

Whether additional pages can be retrieved.

Type: Boolean
Payment
Object

Guest payment details.

FieldDescription
instructionsNot nullable.

Text that is displayed to travelers if a payment type is associated with the reservation.

Type: String
Property
Object

Representation of a physical property, including its units, reservations, and promotions.

FieldDescription
reservationsNot nullable.

List of the property's reservations that match the specified arguments:

  • filter (type: ReservationFilterInput), which enables you to refine the reservations to retrieve. If this argument is not specified, the query returns all reservations for the property.
  • pageSize (type: Int!), which is required and specifies the maximum number of reservations on each page (up to 25) returned by the response. For example, if there are 40 reservations on a property, you can retrieve two pages if this argument is set to 25 (page 1 includes 25 reservations, page 2 includes 15 reservations).
  • after (type: String), which is the cursor from the previous query response that marked the end of the previous page of results.
Type: ReservationsConnection
RateTimeUnit
Enum

Time frame to which the rate is applied.

NameDescription
PER_DAY

Rate is applied per day.

PER_WEEK

Unsupported at this time.

PER_STAY

Unsupported at this time.

RateType
Enum
NameDescription
NET

Net amount (excludes compensation and taxes).

SELL

Gross amount (includes compensation and taxes).

ReconEligibility
Object

Reason(s) why the reservation can or cannot be reconciled.

FieldDescription
invalidScenarios

Reasons and descriptions why the reservation cannot be reconciled.

Type: Array of non nullable InvalidScenario
validScenarios

Reason why the reservation can be reconciled. Values include the following:

  • GUEST_REQUESTED_CANCEL - Traveler cancelled the reservation
  • NO_SHOW - Traveler was a no-show
  • MODIFY_DATES_AMOUNTS - There was a difference in the booking price when the lodging partner charged the traveler (for example, because an extra night was added at the time of stay)
Type: Array of non nullable String
Reservation
Object

Reservation details.

FieldDescription
accessibilityText

Accessibility requests made by the guest for the reservation. We strongly recommend that you include this field in your implementation.

Type: Array of non nullable String
adultCountNot nullable.

Count for all adult guests associated with the reservation.

Type: Int
bedTypes

Bed type of the reservation.

Type: String
businessModelNot nullable.

Entity that collects payment for the reservation.

Type: BusinessModel
checkInDateNot nullable.

Check-in date (format: YYYY-MM-DD) of the reservation.

Type: LocalDate
checkOutDateNot nullable.

Checkout date (format: YYYY-MM-DD) of the reservation.

Type: LocalDate
childAges

Ages of children associated with the reservation.

Type: Array of Int
childCountNot nullable.

Count for all child guests associated with the reservation.

Type: Int
creationDateTimeNot nullable.

Timestamp of when the reservation was created (format: yyyy-mm-ddThh:mm:ssTZD, where TZD is a time zone designator in the form +/-hh:mm). Compare this value to that of lastUpdatedDateTime to determine if a reservation has been modified.

Type: String
idNot nullable.

Expedia's reservation ID.

Type: ID
isReconciled

Whether one or more reconciliation attempts have been made on the reservation.

Type: Boolean
lastUpdatedDateTimeNot nullable.

Date and time when the reservation was last updated. Compare this value to that of creationDateTime to determine if a reservation has been modified.

Type: String
messageThreadId

ID of message thread (conversation) associated with the reservation. This requires implementation and certification of the messaging capability. If no message threads exist for a reservation, null is returned.

Type: ID
multiRoomText

Text that is displayed to guests if there is a multi-room booking associated with the reservation.

Type: String
paymentNot nullable.

Guest payment details.

Type: Payment
primaryGuestNot nullable.

Guest who made the reservation.

Type: Guest
rateIdsNot nullable.

ID of the rate/rate plan and the source of the ID. In the response, when idSource is set to SUPPLIER, the id field returns the same value as returned by the existing booking APIs. However, for Hotel Collect properties, the A- prefix is no longer added to the source value and the A suffix is no longer appended to the rate ID as was done by the booking APIs.

Type: Array of non nullable IdNode
reconciliationEligibility

The reason(s) why the reservation can or cannot be reconciled.

Type: ReconEligibility
reconciliationType

Reconciliation type of the reservation, either MODIFY, CANCEL, NO_SHOW, or null.

Type: String
reservationIdsNot nullable.

IDs associated with the reservation and the source of the IDs.

Type: Array of non nullable IdNode
smokingTypeNot nullable.

Whether smoking is allowed for the reservation.

Type: String
sourceNot nullable.

Source of the reservation. Refer to Booking sources for the list of possible values (though \"A-\" is not included in Hotel Collect sources returned by this API).

Type: String
specialRequest

Text that is displayed to guests if there is a special request associated with the reservation.

Type: String
statusNot nullable.

Current status of the reservation.

Type: ReservationStatus
supplierAmount

Connectivity or lodging partner's amount for the reservation.

Type: SupplierAmount
tidsCode

Travel Industry Designator Service (TIDS) code that allows a reservation to be recognized by industry suppliers.

Type: Int
unitIdsNot nullable.

Known IDs for the unit/room in the source system(s). IDs that are returned depend on where the property was onboarded:

  • If the property was onboarded onto Vrbo, three IDs are returned: the partner’s (external ID), Vrbo’s (Vrbo internal ID), and Expedia's (EID).
  • If the property was onboarded onto Expedia, only the Expedia ID is included in the response.
Type: Array of non nullable IdNode
valueAddedPromotionsNot nullable.

Value add promotion(s) used to book the reservation, which are additional benefits that travelers receive based on loyalty tier status, chosen property, and room type or rate plan they book. If a value add promotion was not used, an empty array is returned. We strongly recommend that you include this field in your implementation to ensure traveler-promised perks can be properly fulfilled by suppliers.

Type: Array of non nullable ReservationValueAddedPromotion
ReservationEdge
Object
FieldDescription
cursorNot nullable.

Cursor value for this edge.

Type: String
nodeNot nullable.

Node that references the reservation data.

Type: Reservation
ReservationFilterInput
InputObject

Parameters used to filter reservations. If more than one filter is specified, the intersection of the filters is returned.

FieldDescription
checkOutDate

Checkout date window for which to filter reservations. Example:

checkOutDate: { from: "2021-08-05", to: "2021-08-07" }
Type: CheckOutDateFilter
lastUpdatedDateTime

Date and time when the reservation was last updated. Compare this value to that of creationDateTime to determine if a reservation has been modified.Example:

 lastUpdatedDateTime: {
    "from": "2022-03-02T10:23:17Z",
    "to": "2022-06-08T12:00:00Z"
  }
Type: LastUpdatedDateTimeFilter
reservationIds

IDs of the reservations to retrieve. Example to retrieve two reservations based on their IDs:

reservationIds: [
  {
    "id": "123HotelCode",
    "idSource": "SUPPLIER"
  },
  {
    "id": "456HotelCode",
    "idSource": "SUPPLIER"
  }
]
Type: Array of non nullable IdNodeInput
ReservationIdSource
Enum

Source system of the reservation ID.

NameDescription
EXPEDIA
VRBO
SUPPLIER
ReservationsConnection
Object

Logical connection to reservations data.

FieldDescription
edgesNot nullable.

Edges in the connection to traverse, each containing a cursor and node.

Type: Array of ReservationEdge
pageInfo

Information about the current page of results.

Type: PageInfo
totalCount

Total number of reservations.

Type: Int
ReservationStatus
Enum

Status of the reservation.

NameDescription
BOOKED
CANCELLED
COMPLETE

For Vrbo reservations only.

CREATED

For Vrbo reservations only.

DECLINED

For Vrbo reservations only.

IN_PROGRESS

For Vrbo reservations only.

INVALID

For Vrbo reservations only.

RESERVED

For Vrbo reservations only.

ReservationValueAddedPromotion
Object

Value add promotion(s) used to book the reservation. If no value add promotion (VAP) was used, an empty array is returned.

FieldDescription
descriptionNot nullable.

Description of the promotion.

Type: String
idNot nullable.

ID of the promotion.

Type: String
String
String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

SupplierAmount
Interface

Implemented by

FieldDescription
currencyCodeNot nullable.

Currency in which the amount is shown.

Type: String
rateTypeNot nullable.

Rate type.

Type: RateType
SupplierAmountCompensation
Object

Compensation information associated with the reservation for this date range.

FieldDescription
acceleratorPercent

Accelerator percentage, expressed as a fraction of 1 (for example, 0.25).

Type: Float
basePercent

Compensation base percentage, expressed as a fraction of 1 (for example, 0.25).

Type: Float
SupplierFeeType
Enum

Type of fee charged by the lodging partner.

NameDescription
BASE_RATE

Nightly rate with no additional taxes, fees, or surcharges.

EXTRA_GUEST_FEES

Fees that are included in the price that guests see when booking. They are paid in advance for Expedia Collect reservations or upon arrival for Hotel Collect reservations.

SERVICE_FEES

Fees that only apply to guests who make use of specific facilities or services, such as resort fees, parking fees, or fees for rollaway beds.

RECONCILED_AMOUNT

Updated rate, which must be the commissionable value for the stay date. Amounts for dates included in the original reservation cannot be modified to a value of three times more than the commissionable rate applicable to that date.

SupplierLoyaltyPlanInfo
Object

Details about the frequent traveler reward program. This field identifies if the traveler is a member of the supplier's loyalty program to ensure the supplier is able to greet the guest accordingly and award loyalty points as needed.

FieldDescription
membershipNumber

Traveler's membership number.

Type: String
planCode

Reward program code.

Type: String
SupplierRate
Object
FieldDescription
fromDateNot nullable.

Date when the rate becomes effective (format: YYYY-MM-DD).

Type: LocalDate
rateItemsNot nullable.

Itemized list of fees.

Type: Array of non nullable SupplierRateItem
rateTimeUnitNot nullable.

Time unit of the rate.

Type: RateTimeUnit
toDateNot nullable.

Date when the rate expires (format: YYYY-MM-DD).

Type: LocalDate
SupplierRateItem
Object
FieldDescription
amountNot nullable.

Amount of the fee.

Type: Float
feeTypeNot nullable.

Type of fee for this itemized rate.

Type: SupplierFeeType
SupplierTotal
Object
FieldDescription
amountAfterTaxNot nullable.

Total amount of the fee after tax is applied.

Type: Float
amountBeforeTaxNot nullable.

Total amount of the fee before tax is applied.

Type: Float
compensationNot nullable.

Compensation information associated with the reservation.

Type: SupplierAmountCompensation
TravelPurpose
Enum

Values for a guest's travel purpose, to identify business bookings.

NameDescription
NONE
KNOWN_BUSINESS_VISIT
SUSPECTED_BUSINESS_VISIT
KNOWN_PERSONAL_VISIT
SUSPECTED_PERSONAL_VISIT
ZoneDateTime
ZoneDateTime

A type representing a date and time with a time zone in the format YYYY-MM-DDTHH:mm:ssTZD, where TZD is a time zone designator in the form +/-hh:mm).