Getting startedReviews

Intro to reviews

The reviews capability is now provided by the Lodging Supply GraphQL API, and it enables lodging partners to manage property reviews. After you integrate this capability, each lodging partner can retrieve approved reviews collected by the Expedia platform after travelers check out.

To support this functionality, the API now offers the following:

  • reviews query, which enables partners to retrieve review data including review ID, reservation ID, traveler name, Expedia property ID (EID), review title and body, review creation and update time, traveler ratings, and property manager response
  • setReviewResponse mutation, which enables partners to respond to traveler reviews

In addition, a notification service (webhooks) is provided to enable lodging partners to receive real-time notifications when

  • Travelers leave a review (GuestReviewSubmitted)
  • Traveler reviews are approved (ReviewsApproved)
  • Lodging partner responses are approved (ReviewsManagementResponseApproved)
  • Lodging partner responses are rejected (ReviewsManagementResponseRejected)

To receive notifications, the partner must subscribe to notification events after you implement them.

All requests must be made over a secure connection. All response bodies, including errors, are encoded in JSON.

Download the launch kit here.

Workflow

After the reviews capability and notifications are implemented, the following workflow is possible:

  1. Traveler stay ends (checks out).
  2. Expedia solicits the traveler to submit a review.
  3. Traveler submits a review.
  4. GuestReviewSubmitted webhook notification is sent to the lodging partner.
  5. If the review is approved, ReviewsApproved notification is sent to the lodging partner. If the review is rejected, steps 2-3 are repeated.
  6. Once approved, the review is available via the API and is displayed on the Expedia site.
  7. Lodging partner uses the reviews query to retrieve the review and its ID.
  8. Lodging partner responds to the review using the setReviewResponse mutation.
  9. If the response is approved, ReviewsManagementResponseApproved notification is sent to the partner, and the response is displayed on the Expedia site. If the response is rejected, the ReviewsManagementResponseRejected notification is sent.

Implementation details

Be mindful of the following as you implement the reviews query:

  • Only approved reviews can be retrieved; reviews that have not been submitted for moderation (pending) and rejected are not returned. Note that reviews may be pending for up to 14 days depending on the lodging partner’s actions and review content.

  • Once a stay ends, the traveler has 180 days to review their stay.

  • Reviews are not eligible for a management response (isEligibleForResponse: false) under the following conditions:

    • An existing approved management response exists
    • The review was imported by the connectivity partner
    • A management response has been submitted and is in moderation, so it has not yet been approved or rejected

  • Ratings on Hotels.com are displayed using a 10-point scale, which is calculated by doubling the rating provided through the API. For example, if a traveler submits a 2, 4 is displayed on Hotels.com.

  • Review data includes details such as review ID, reservation ID, header, review text, score, reviewer name, and reservation dates. Total review count can also be retrieved.

  • Reviews can be filtered by ID, review source (imported or platform), creation date, update date, and whether the review has a response. Reviews can also be ordered in the response by these factors.

  • To receive notifications, your endpoint must use Transport Layer Security (TLS) 1.2 or 1.3, to provide over-the-wire encryption (HTTPS).

When implementing the setReviewResponse mutation, be aware of the following:

  • Responses can be submitted for eligible, approved reviews only.

  • If a review already has a pending or approved response, then another cannot be submitted for that review. If no response exists or the response was rejected, then a response can be submitted.

Limitations

Be aware of these as you integrate the reviews capability:

  • If a lodging partner has a property listed on both Vrbo and Expedia, reviews are retrieved separately for each channel.
  • When retrieving reviews, up to 10 reviews can be returned per page.
  • To retrieve or update Expedia property reviews, you must specify the Expedia ID.
  • When responding to a review using the setReviewResponse mutation, you must specify the property’s Expedia ID (EID).
  • Property manager responses are only eligible for platform reviews, if they do not already exist.
  • The rate limit is currently set to five transactions per second (TPS).

Retrieving reviews

After you implement the reviews query, lodging partners can retrieve approved property reviews. The query enables partners to retrieve all reviews for a property or retrieve a specific review (based on its ID). In the orderBy object, you can set how to sort the reviews (for example, by creation date) and whether they sorted in ascending or descending order.

By property ID

Here is an example that retrieves all reviews for a property and paginates the reviews, 10 per page (as specified by the pageSize: 10 filter).

  • This example retrieves reviews for an Expedia property, therefore the Expedia ID is provided (id: "9309913", idSource: EXPEDIA).

  • The query includes the ids object in the payload request, so that both the Expedia ID and supplier ID are returned.

  • Reviews are retrieved and sorted by reservation check-in date, from newest to oldest.

The response includes three reviews, which are not eligible for a management response ("isEligibleForResponse": false) because the management responses are approved.

1query {
2 property(id: "9309913", idSource: EXPEDIA) {
3 reviews(pageSize: 10) {
4 totalCount
5 cursor
6 reviews {
7 id
8 reservation {
9 reservationIds {
10 id
11 idSource
12 }
13 status
14 primaryGuest {
15 firstName
16 lastName
17 }
18 }
19 propertyId {
20 id
21 idSource
22 }
23 status
24 brandName
25 source
26 createdDateTime
27 lastUpdatedDateTime
28 title {
29 value
30 locale
31 }
32 body {
33 value
34 locale
35 }
36 starRatings {
37 category
38 value
39 }
40 isEligibleForResponse
41 response {
42 status
43 createdDateTime
44 lastUpdatedDateTime
45 body {
46 value
47 locale
48 }
49 }
50 }
51 }
52 }
53}

By review ID, review details, or reservation IDs

The reviews query provides the ability to filter reviews by

  • Review ID
  • Creation date
  • Update date
  • Review source
  • Reservation ID
  • Whether an owner or property manager response exists

Here are examples of filters:

  • By review source and creation date:

    query { 
    property(id: "9309913", idSource: EXPEDIA) { 
      reviews( 
        pageSize: 10,  
        filter: { 
          source: "PLATFORM", 
          createdDate: {from: "2022-01-30", to: "2022-01-31"} 
        } 
      ) { 
      … 
    
  • By reservation ID:

    query { 
    property(id: "9309913", idSource: EXPEDIA) { 
      reviews( 
        pageSize: 10,  
        filter: { 
          reservation: { 
            reservationIds: { 
              id: "1401556215",  
              idSource: EXPEDIA 
            } 
          } 
        ) { 
      … 
    

The following full example retrieves a property’s reviews and then filters the results by a specific review ID. In the response, note that the review is not eligible for a management response ("isEligibleForResponse": false) because the management response has not been submitted for moderation.

1query {
2 property(id: "9309913", idSource: EXPEDIA) {
3 reviews(pageSize: 10, filter:{reviewId: "61f87508de53060cb1ff59e9"}) {
4 totalCount
5 cursor
6 reviews {
7 id
8 reservation {
9 reservationIds {
10 id
11 idSource
12 }
13 status
14 primaryGuest {
15 firstName
16 lastName
17 }
18 }
19 propertyId {
20 id
21 idSource
22 }
23 status
24 brandName
25 source
26 createdDateTime
27 lastUpdatedDateTime
28 title {
29 value
30 locale
31 }
32 body {
33 value
34 locale
35 }
36 starRatings {
37 category
38 value
39 }
40 isEligibleForResponse
41 response {
42 status
43 createdDateTime
44 lastUpdatedDateTime
45 body {
46 value
47 locale
48 }
49 }
50 }
51 }
52 }
53}

Responding to reviews

Use this mutation to respond to a traveler review.

1mutation {
2 setReviewResponse(
3 propertyId: "9309913",
4 propertyIdSource: EXPEDIA,
5 reviewId: "61f87508de53060cb1ff59e9",
6 body: {
7 value: "Thank you very much for the generous review.",
8 locale: "en-US"
9 }
10 ) {
11 createdDateTime
12 status
13 body {
14 value
15 locale
16 }
17 }
18}