Prerequisite: Availability and Rates API | Booking Notification or Booking Retrieval API
Intro to reservations
The reservations capability of the Lodging Supply GraphQL API enables a partner to retrieve reservations made on an Expedia Group point-of-sale. It also enables lodging partners to update reservations in their system based on changes in our system (on or after a reservation’s check-in date).
Download the launch kit here.
reservations query is provided to enable a partner to retrieve reservations made on an Expedia Group point-of-sale. Once the query is implemented, lodging partners can use this capability to
- Filter reservations by checkout date to export in-flight reservations when onboarding a new property to their connected software solution.
- Filter reservations by last updated date to backload reservation data for reservation events that were impacted by connection outage to our reservation delivery APIs (Booking Retrieval and Booking Notification).
- Filter by reservation IDs to pinpoint specific reservations and associated details, if a partner need to verify perks, accessibility request, and loyalty status prior to arrival.
Note: This capability retrieves reservations for properties that were onboarded to Expedia sites only. Retrieving reservations for Vrbo properties is not supported at this time.
Be aware of these limitations when implementing the reservation retrieval feature of the reservations capability:
The reservations retrieval capability is read-only and returns a summary of each reservation. Write operations are not supported at this time.
The following data points are not currently retrieved: credit card information, compensation, and per-stay and per-person fees.
Only reservations for local inventory are retrieved.
The state of a failed reservation cannot be changed once retrieved. If a reservation failed to be delivered by the Booking Notification or Booking Retrieval API, this capability enables you to retrieve these reservations, though modifications or cancellations to those reservations will be delivered using the secondary delivery method, such as email or fax.
You can query for reservations based on checkout dates, reservation ID, and dates when reservations were last updated. You cannot query for reservations based on booking dates.
Up to 10,000 reservations can be retrieved using this capability.
Minimum certification requirements
To adopt the reservation retrieval feature, you must successfully complete end-to-end certification with Expedia Group teams.
You are expected to retrieve reservations by all filters: checkout date, last updated date and time, and reservation IDs.
The following information must be surfaced in your user interface, saved, and passed to your property management system (PMS). Examples will be requested during certification.
- Perks / Value add promotions
- Accessibility request
- Loyalty status
- You must be able to support the
reconciliationEligibilityobject if adopting the reservation update feature.
To enable lodging partners to reconcile reservations, the
changeReservationReconciliation mutations are provided. Once implemented, lodging partners can use this feature to
- Cancel a reservation if the guest does not show up or if requested by the guest, enabling a partner to specify the penalty amount that the guest was charged and ensure that Expedia Group will charge a commission on the penalty amount that the guest was charged instead of the original amount.
- Update a reservation if the travel dates or daily rates applied to the reservation were modified, enabling the partner to communicate updated stay dates or rates to Expedia Group so that we charge commission on the amount that was charged to the guest.
If you intend to implement the reservation reconciliation feature, you must implement reservation retrieval, which enables lodging partners to determine whether reservations are eligible for reconciliation. Partners will not need to rely on error messaging or hard-coded reconciliation criteria in their systems. Instead, they can proactively query for eligibility criteria so that they know exactly which reconciliation actions can be taken.
To determine if a reservation is eligible for reconciliation, include the
reconciliationEligibility object in the
reservations query, as documented here.
Here are the validation rules that determine if a reservation can be reconciled or updated:
- Only Hotel Collect reservations can be reconciled or updated.
- For reconciliation, check-in dates should be the current date and/or in the past.
- Reservations can be reconciled from the check-in date until the fourth day of the month after the checkout date (you cannot reconcile future reservations). For example, if a guest checks out on March 2nd, the partner can reconcile the reservation until April 4th. If you do not reconcile the reservation on time, the invoice includes the booked amount.
- Cancellation fee or no-show fee cannot be more than the initial booking amount.
- Amounts for dates included in the original reservation cannot be modified to a value of three times above the actual amounts applicable to that date (for additional dates, there is no limit).
- Up to three days can be added before the original check-in date or up to three days after the original checkout date.
Be aware of these limitation when implementing the reservation update feature:
Reservation updates and cancellations cannot be made before the reservation’s check-in date.
Reconciliation can be performed on Hotel Collect reservations for independently managed properties operating under the Hotel Collect or Expedia Traveler Preference business model. This capability is not available for Expedia Collect or Hotel Collect Group Reconciliation properties.
Only Expedia IDs (property and reservation IDs) are allowed as arguments.
Reservations can be reconciled up to three times when modifying a reservation and only once when cancelling a reservation. (However, partners cannot reset a cancellation using the API; they must use Partner Central to do so).
Minimum certification requirements
To adopt the reservation update feature, you must successfully complete end-to-end certification with Expedia Group teams. You are expected to confirm reservation update eligibility by retrieving reservations using the reservation retrieval feature (by reservation ID, checkout date, or last updated date and time) and the
For post-stay reconciliation, you must be able to perform following actions:
- Cancel a reservation as requested by the guest. In the event of no-show, you must be able to cancel a reservation after the check-in date.
- Update a reservation's stay dates and amounts after the check-in date.
- Inform Expedia Group of the final reservation status regardless of any financial implication, even when the reservation is non-refundable.
Comparison to booking APIs
If you have coded to the Booking Notification or Booking Retrieval API, be aware of these differences in the response attributes of this API:
|Booking APIs||Reservations capability|
|Prefix the value of the rate ID in the ||Removes the prefix from the rate ID and provides the |
|Offer three types of transactions: original reservation, modified reservation, and cancelled reservation||Provides the |
|Bed types, smoking preference, multi-room reservation messages, and payment instructions are represented within ||Provides the |
|Return the total amounts after tax along with the tax amount||Returns the total amount after tax and the total amount before tax (a difference between the two indicates the tax amount)|
In addition, the Lodging Supply GraphL API returns Unicode characters if the guest provided these in the reservation. This includes non-ASCII characters and non-English characters such as Chinese and Japanese, which could be included in guest names and special requests. Therefore, you must support all UTF-8 and Unicode characters.