Reservation retrievalCopy link

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 queried 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

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.

1. The lodging partner retrieves an opaque payment token by including the payment object in the reservations query.
2. 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 the payment object to ensure you are charging the accurate amount. (Note EVC best practices here.)

  To retrieve guest credit card information, reference the amount field on Installment 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:

1{ 
2  "data": { 
3    "property": { 
4      "reservations": { 
5        "edges": [ 
6          { 
7            "node": { 
8              "cancellationPolicy": { 
9                "tiers": [ 
10                  { 
11                    "cancellationWindow": { 
12                      "temporalUnit": "HOUR", 
13                      "cutoff": 48 
14                    }, 
15                    "penaltyRule": { 
16                      "type": "NUMBER_OF_NIGHTS", 
17                      "percentage": null, 
18                      "costFlatAmount": null, 
19                      "priceAmount": null, 
20                      "numberOfNights": 1 
21                    } 
22                  }, 
23                  { 
24                    "cancellationWindow": { 
25                      "temporalUnit": "HOUR", 
26                      "cutoff": 12000 
27                    }, 
28                    "penaltyRule": { 
29                      "type": "PERCENTAGE", 
30                     "percentage": 0, 
31                      "costFlatAmount": null, 
32                      "priceAmount": null, 
33                      "numberOfNights": null 
34                    } 
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 and priceAmount 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:

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": 100 
16                    } 
17                  }, 
18                  { 
19                    "dueDate": "2024-03-02", 
20                    "amount": { 
21                      "currencyCode": "JPY", 
22                      "amount": 15625 
23                    } 
24                  }, 
25                  { 
26                    "dueDate": "2024-04-01", 
27                    "amount": { 
28                      "currencyCode": "JPY", 
29                      "amount": 15525 
30                    } 
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

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 the rate 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.