Reservation retrieval
The reservations
query enables partners to retrieve reservations made on Expedia Group points-of-sale. The complete reservation payload should be retrieved following a reservation notification to ensure connected systems reflect a complete picture of the reservation details. Reservation retrieval also enables on-demand, dynamic, and bulk query access to ensure reservations details are available if reservation details need to be captured or updated outside of traditional fulfillment flow. For example, connected systems can query for upcoming reservations when onboarding properties to ensure reservations are properly imported. Or, reservations can be queries if the delivery of reservation notifications was unsuccessful due to planned downtime or unexpected system outage.
Using this query alleviates the need to manually export and import reservations or manually enter all reservations details into partner systems. In addition, in the event of an Expedia or partner outage, reservations are delivered to partners via in email messages. This API alleviates the manual work required to enter these reservations in their systems.
After the reservations
query is implemented, lodging partners can retrieve and filter reservations by
- Checkout date to export in-flight reservations when onboarding a new property to their connected software solution
- Last updated date to backload reservation data for reservation events that were impacted by connection outage
- Reservation IDs to pinpoint specific reservations and associated details, if a partner need to verify perks, accessibility request, and loyalty status prior to arrival
- Check-in date
- Reservation status
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.
The following sections provide an overview of retrieval features.
Detailed reservation amounts
When amounts
is included in its payload, the reservations
query provides access to comprehensive reservation amount values. This model closely aligns to the Expedia Partner Central (EPC) reservation amounts model and should help promote a consistent end-user experience between EPC and connected systems. Amount details include
- Compensation amounts, margin percentages, and accelerators
- Partner payout values
- Per-stay (summary) and nightly (detailed) breakdown
- Addition of auto-rate match and adjusted amounts
Some of the benefits delivered through this model include (but are not limited to)
- More comprehensive access to amount details not historically available through our XML APIs
- Specificity in amount breakdown and better clarity into calculations
- Improved compensation insights
- Visibility into applied promotions and cancellation penalties
- Summary and nightly views available for all reservation
- Dynamic content that updates throughout the reservation lifecycle
Detailed amounts enable you to implement a refreshed display within your system to bring clarity to the reservation amount value breakdown. Refer to UI guidelines for recommendations.
The following describes the primary use cases and associated best practices that should be implemented when adopting the enhanced supplier amounts feature.
Reservation delivery
If you implemented reservation delivery, include the
ReservationAmounts
object in your query, and use the reservation ID filter after receiving a reservation webhook notification to ensure you have the most up-to-date payment information.Reservation update
If you implemented reservation update, include the
ReservationAmounts
element in your query, and use the reservation ID filter following your reservation update to ensure your system has the most up-to-date reservation amount information.Property onboarding and backloading reservations
When a property with upcoming Expedia Group reservations onboards to your connected system, use the checkout date filter to retrieve and import these reservations in bulk to the new connected system. This ensures accurate reservation and inventory representation. Query for the
ReservationAmounts
object during this workflow to verify the most up-to-date reservation amount information.Connectivity outage and reservation recovery
At times, Expedia may be unable to successfully deliver a reservation to your connected system through the API. When this occurs, these reservations are sent in direct email notifications to the property. Use the last updated date filter to query the period for which the outage occurred to recover the impacted reservations. Query for the
ReservationAmounts
object during this workflow to verify the most up-to-date reservation amount information.
Be aware that a property's business model impacts the total amount to charge or collect for a reservation:
These fields indicate a Hotel Collect reservation:
businessModel: HOTEL_COLLECT
remittanceType: null
supplierOperatingModel: AGENCY
The collect amount (type: COLLECT_AMOUNT
) indicates the amount to charge the guest and is the same as the guest payment (COLLECT_AMOUNT value = GUEST_PAYMENT value).
These fields indicate an Expedia Collect reservation:
businessModel: EXPEDIA_COLLECT
remittanceType: NET
supplierOperatingModel: MERCHANT
The collect amount (type: COLLECT_AMOUNT
) indicates the amount to charge Expedia Group and is the partner's total payout (COLLECT_AMOUNT value and PAYOUT value = SUBTOTAL + TAX + FEE + PER_STAY_FEE + PER_STAY_TAX + EXTRA_PERSON_CHARGE).
These fields indicate an Updated Expedia Collect reservation with net remittance:
businessModel: EXPEDIA_COLLECT
remittanceType: NET
supplierOperatingModel: AGENCY
The collect amount (type: COLLECT_AMOUNT
) indicates the amount to charge Expedia Group and is the partner's earnings after deductions (COLLECT_AMOUNT value = PAYOUT value).
These fields indicate an Updated Expedia Collect reservation with gross remittance:
businessModel: EXPEDIA_COLLECT
remittanceType: GROSS
supplierOperatingModel: AGENCY
The collect amount (type: COLLECT_AMOUNT
) indicates the amount to charge Expedia Group and is the total amount paid by the guest (COLLECT_AMOUNT value = GUEST_PAYMENT value).
Payment management
Traveler payment information is critical and foundational to a reservation’s lifecycle. Currently, connected partners must manually collect payment information (except for Expedia Collect + non-EVC bookings) by direct contact with the traveler, through contact with Expedia Group support teams, or by accessing the EPC extranet. This manual intervention can drive up operational costs for partners and can lead to poor traveler experiences. With the introduction of the payment management feature, connected partners now have on-demand, post-booking, bulk access to dynamic guest credit card and Expedia Virtual Card (EVC) data.
The reservation management capability now enables you to retrieve credit card and Expedia Virtual Card (EVC) information on-demand, alleviating the need to manually collect this information as part of the following workflows:
Software onboarding and switching: When a property onboards to a new software instance, a lodging partner must retrieve and backload reservation data for upcoming reservations, including credit card and EVC information.
Outage: If a partner experiences a connectivity outage that impacts the delivery of reservation details through the API, they will need to backload the reservation data that was missed during the outage period, including credit card and EVC information.
To support this enhancement, a new payment object has been added to the reservations
query, and a new API is introduced to retrieve the PCI data.
- The lodging partner retrieves an opaque payment token by including the
payment
object in thereservations
query. - The partner calls the
paymentInstrument
query to retrieve the credit card and EVC information using the opaque token.
This token-based design mitigates the risk and impact of a breach by further promoting Payment Card Industry (PCI) data security and privacy, and it sets a new standard for securely passing payment-related details through an Expedia API. Note that if a lodging partner is not PCI compliant, only EVC information can be retrieved. (null is returned instead of guest credit card data if the traveler used a credit card to book the reservation.)
The following describes the primary use cases and associated best practices that should be implemented when adopting the payment management feature.
Reservation delivery
If you implemented reservation delivery, you can retrieve the reservation’s payment information by requesting the
payment
object.Property onboarding and backloading reservations
When a property with upcoming Expedia Group reservations onboards to your connected system, use the checkout date filter to retrieve and import these reservations in bulk to the new connected system. This ensures accurate reservation and inventory representation. Query for the
payment
object during this workflow to retrieve a token that can then be used to verify the most up-to-date traveler payment details as needed.Connectivity outage and reservation recovery
At times, Expedia may be unable to successfully deliver a reservation to your connected system through the API. When this occurs, these reservations are sent in direct email notifications to the property. Use the last updated date filter to query the period for which the outage occurred to recover the impacted reservations. Include the
payment
object during this workflow to verify the most up-to-date traveler payment details as needed.Payment management
The Expedia Virtual Card (EVC) is activated on the reservation’s check-in date; EVCs cannot be charged prior to the check-in date. Therefore, no pre-authorizations or deposit charges should be charged to the card prior to check-in. Reference the
activationDate
field to verify when the EVC will be ready to charge. Then, query for the payment details on the day of check-in to ensure payment information is current. Charge the card in full by referencing thepayment
object to ensure you are charging the accurate amount. (Note EVC best practices here.)To retrieve guest credit card information, reference the
amount
field onInstallment
to ensure you are charging the accurate amount to the guest credit card. Hotel Collect bookings may have unique deposits and payment schedules configured. These fields are included in the reservation payload if these values need to be referenced during the traveler payment management process.
Cancellation policy
A reservation's cancellation policy can now be retrieved to provide parity with EPC (except for seasonal exceptions, which are not yet supported by the API). The cancellationPolicy
object is now available in your reservations
query payload and it describes the policy that was in place when the reservation was made (currently available in Product API).
To help you understand how to read cancellation policy details reported by the query, consider this response:
- Cancellation policy
1{2 "data": {3 "property": {4 "reservations": {5 "edges": [6 {7 "node": {8 "cancellationPolicy": {9 "tiers": [10 {11 "cancellationWindow": {12 "temporalUnit": "HOUR",13 "cutoff": 4814 },15 "penaltyRule": {16 "type": "NUMBER_OF_NIGHTS",17 "percentage": null,18 "costFlatAmount": null,19 "priceAmount": null,20 "numberOfNights": 121 }22 },23 {24 "cancellationWindow": {25 "temporalUnit": "HOUR",26 "cutoff": 1200027 },28 "penaltyRule": {29 "type": "PERCENTAGE",30 "percentage": 0,31 "costFlatAmount": null,32 "priceAmount": null,33 "numberOfNights": null34 }35 }36 ]37 },38 "reservationIds": [39 {40 "id": "790467760",41 "idSource": "EXPEDIA"42 },43 {44 "id": null,45 "idSource": "SUPPLIER"46 }47 ],48 "source": "Expedia",49 "checkInDate": "2024-01-23",50 "checkOutDate": "2024-01-25",51 "businessModel": "EXPEDIA_COLLECT",52 "status": "BOOKED"53 }54 }55 ]56 }57 }58 }59}
This example response shows the following cancellation policy rules:
If the reservation is cancelled less than 24 hours before the check-in date (up to 11:59p local property time), no refund is issued (100% of the reservation amount is charged as a penalty fee)
If the reservation is cancelled 1-10 days (240 hours) before the check-in date (up to 11:59p local time), 50% of the reservation amount is charged as a penalty fee
If the reservation is cancelled more than 10 days before the check-in date (up to 11:59p local time), $100 is charged as a cancellation penalty and the provider will receive $80 ($100 minus commission)
If the booking is Expedia Collect with a flat fee penalty type, the
costFlatAmount
andpriceAmount
values differ as shown in this example
Payment schedule
A reservation's payment schedule can now be retrieved to provide parity with Expedia Partner Central (EPC). The payment : installments
object in your reservations
query payload provides the payment schedule used to collect payment for the reservation (currently available in Deposit API).
To help you understand how to read a payment schedule reported by the query, consider this response:
- Payment schedule
1{2 "data": {3 "property": {4 "reservations": {5 "edges": [6 {7 "node": {8 "payment": {9 "instructions": "Expedia collects payment from traveler: Hotel charges Expedia Virtual Card.",10 "installments": [11 {12 "dueDate": "2024-02-16",13 "amount": {14 "currencyCode": "JPY",15 "amount": 10016 }17 },18 {19 "dueDate": "2024-03-02",20 "amount": {21 "currencyCode": "JPY",22 "amount": 1562523 }24 },25 {26 "dueDate": "2024-04-01",27 "amount": {28 "currencyCode": "JPY",29 "amount": 1552530 }31 }32 ]33 },34 "reservationIds": [35 {36 "id": "790467760",37 "idSource": "EXPEDIA"38 },39 {40 "id": null,41 "idSource": "SUPPLIER"42 }43 ],44 "checkInDate": "2024-04-01",45 "checkOutDate": "2024-04-05"46 }47 }48 ]49 }50 }51 }52}
The response shows payments are collected as follows:
When the reservation was made (February 2, 2024), a deposit of 100 Yen is collected
Four weeks and two days before arrival, half of the reservation amount is collected (minus the deposit)
At check-in, the remaining balance is collected
Corporate details
Note: This is a beta feature that is available to pilot partners only. Contact your Technical Account Manager if you are interested in retrieving corporate traveler details.
As Expedia's B2B distribution network continues to grow, corporate travel is becoming an increasingly important segment. Providing property staff with access to clear, actionable details about corporate travelers enhances the ability to deliver a tailored and efficient experience, ensuring corporate travelers have a seamless stay.
Corporate traveler identifiers – Key identifiers such as travel purpose, affiliate source, and company name provide partners with insights that help personalize the experience and ensure that corporate travelers receive the services and benefits tailored to their corporate needs.
Affiliate virtual credit card (VCC) identifier and handling instruction – With the inclusion of handling instructions for affiliate virtual credit cards within the API payload, partners can easily process payments linked to corporate accounts. This ensures smooth transactions and compliance with corporate billing standards.
Corporate invoices and VAT – Clear access to corporate invoice and VAT details within the traveler profile allows for seamless billing processes, catering to both corporate traveler preferences and tax requirements to support streamlined corporate expense management.
Business rates and supplier loyalty – Understanding a corporate guest’s business rate eligibility and supplier loyalty status enables the partner to apply the correct pricing, ensuring both competitive rates and the honoring of loyalty benefits for frequent business travelers.
These details can be retrieved using the reservations
query and the paymentInstrument
query. These details not only help partners provide personalized services to corporate travelers but also drive operational efficiency, fostering stronger relationships with corporate clients and increasing future business opportunities.
The new corporate VCC and invoice fields should be implemented within your existing payment management and billing interfaces to ensure that partners understand how to properly handle affiliate VCCs before to attempting to charge and process them and how to properly issue invoices following traveler stays.
Be mindful of these considerations as you implement this enhancement:
Affiliate VCCs are issued by third parties and are not equivalent to Expedia Virtual Cards.
Travelers can book and pay for Hotel Collect reservations using a personal credit card or an affiliate VCC.
Depending on the distribution partner’s API configuration, you may see relevant free-text instructions also passed through the
PaymentInstructions
object.To ensure that corporate travelers can be identified by lodging partners, we recommend that you implement the following fields on the
reservations
query. These elements will assist the lodging partner in its ability to facilitate a tailored corporate traveler experience.travelPurpose
– Whether the guest is traveling for business or leisure.affiliateSource
- Point of sale of the reservation. It is important that lodging partners reference this value when greeting or redirecting travelers. When a reservation is sourced through an affiliate travel management agency, travelers should not be greeted or identified as an Expedia traveler. It is also important that travelers are redirected to the affiliate partner for reservation support, rather than Expedia.company:name
– Corporate entity with which the business traveler is associated and the company name that should be listed on the invoice.alternativeIds:itineraryReference
- Unique reference code that is shared with the traveler and should assist in streamlining communication between the lodging partner, traveler, and travel management agency.rateIDs
- Rate plan ID that will provide partners with visibility into whether a reservation was booked with a business rate plan.supplierLoyaltyInfo
– Information that is often attached to business rate plans and is used to ensure partners are aware of a business traveler’s loyalty program, to ensure these travelers and loyalty benefits are communicated and managed accordingly.
Implementation details and limitations
Only reservations for local inventory are retrieved. (properties that were onboarded through the Availability and Rates API or ARI API).
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.
Up to 10,000 reservations can be retrieved at a time.
Reservations can be queried 465 days in the past and up to 500 days in the future.
If you retrieve the
date
field in therate
object, check-in and checkout values represent original (pre-reconciled) check-in and checkout dates.If you retrieve payment tokens for Hotel Collect and Expedia Collect reservations in the same query, a payment token will be returned for each reservation. Once retrieved, a payment token is valid for one hour only.
When retrieving payment information for reservations with checkout dates in the past, verification number (CVV) is not retrieved for reservations made with a guest credit card (Hotel Collect).
If a partner is not PCI compliant, the request for guest credit card data will return null (no payment token will be provided).
If a reservation is not confirmed within the expiry window, it is sent in an email notification to the property. (Subsequent events for the reservation, such as modification or cancellation, are also sent via email.) Use the last updated date filter of the
reservations
query to filter reservations based on the period for which the outage occurred, so that you can recover the impacted reservations.
Minimum certification requirements
To adopt the reservation retrieval feature, you must successfully complete end-to-end certification with Expedia Group teams. Refer to the reservations
query reference for field and object descriptions.
Feature | Functionality support |
---|---|
Retrieve reservations using filters | You must retrieve reservations using these filters:
|
Retrieve payment data | You must retrieve the payment object, including the following details. Using this feature, partners can have on-demand, post-booking, bulk access to dynamic traveler credit card and Expedia Virtual Card (EVC) data.
|
Retrieve reservation details | You must retrieve these fields and objects:
|
Retrieve corporate traveler details | You must retrieve these fields and objects:
|
Retrieve reservation amounts |
|
Support Updated Expedia Collect attributes | You must retrieve these fields using the reservations query:
|
Display errors | You must provide an error display on system UI. |