Prerequisite: Availability and Rates API | Booking Notification or Booking Retrieval API
Intro to reservations
Note: Before implementing reservation retrieval or update, contact your Technical Relationship Manager to discuss upcoming enhancements to the API that might impact your development efforts.
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.
Reservation retrieval
The 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.
Limitations
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
reconciliationEligibility
object if adopting the reservation update feature.
Reservation update
The reservations capability enables lodging partners to update reservations on or before a reservation’s check-in date. After the cancelReservation
mutation is implemented, the following actions are available to partners:
Cancel a reservation as requested by the guest
A lodging partner can request to cancel a reservation and agree to waive (or refund, if applicable) any cancellation fees and other amounts associated with the reservation. Expedia Group will not charge any compensation for these waived amounts.Cancel a reservation if the method of payment is invalid (Hotel Collect only) If the credit card provided by the traveler is invalid, the partner can request to cancel the reservation and agree to waive (or refund, if applicable) any cancellation fees and other amounts associated with the reservation. Expedia Group will not charge any compensation for these waived amounts.
In addition, the reservations capability enables lodging partners to reconcile reservations on or after a reservation’s check-in date as follows:
Cancel a reservation if the guest does not show up or if requested by the guest After the
cancelReservationReconciliation
mutation is implemented, a partner can 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 After the
changeReservationReconciliation
mutation is implemented, the partner can 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 update 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 updates, include the reconciliationEligibility
object in the reservations
query, as documented here.
Note: After a reservation is updated, notifications are not sent through any of the booking APIs (Booking Notification, Booking Confirmation, Booking Retrieval), if they are used to maintain inventory. Similarly, no changes are made to inventory to reflect the update.
Limitations
Be aware of these limitation when implementing the reservation update feature:
Reconciliation (on or after a reservation’s check-in date) 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 Hotel Collect Group Reconciliation properties.
Updates (before a reservation’s check-in date) can be performed on Expedia Collect and Hotel Collect reservations.
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 reconciliationEligibility
object.
For pre-arrival cancellation, you must be able to perform following actions:
- Cancel a reservation if the method of payment is invalid (Hotel Collect).
- Cancel a reservation as requested by the guest (Hotel Collect and Expedia Collect).
For reconciliation after the guest arrives, 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 source field with an "A-" to indicate that a reservation is Hotel Collect, such as A-Expedia or A-Hotels.com | Removes the prefix from the rate ID and provides the businessModel field so that partners can identify the collection model |
Offer three types of transactions: original reservation, modified reservation, and cancelled reservation | Provides the status field, which currently only supports BOOKED and CANCELLED values |
Bed types, smoking preference, multi-room reservation messages, and payment instructions are represented within SpecialRequest s with unique request codes | Provides the bedTypes , smokingType , and multiRoomText fields, and the specialRequest field returns the traveler-specific requests for reservations |
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.