API introCopy link

The Lodging Supply GraphQL API enables Expedia connectivity providers to retrieve property information, reservation data, regulatory information, and more. This is a GraphQL API, and all request and response bodies, including errors, are encoded in JSON. All requests and responses must be made over a secure connection.

Endpoint

https://api.expediagroup.com/supply/lodging/graphql

All requests must be made over a secure connection. All response bodies, including errors, are encoded in JSON. If no response is returned within 65 seconds, the request has timed out; set your retry logic accordingly.

Use the POST method as shown in this syntax statement:

curl --request POST \
     --url https://api.expediagroup.com/supply/lodging/graphql \
     --header 'Authorization: Bearer {token}' \
     --header 'Content-Type: application/json' \
     -d ' {
      property(id: "{id}")
        ...
      }
     '

Even though a POST is sent to the GraphQL endpoint, data will only be retrieved, not modified, because the body contains queries only.

Authentication and authorization

This API uses OAuth2 for delegating access to resources. Rather than passing username/password credentials with each request, you can periodically obtain an access token from the OAuth2 server to send within API requests in the form of a bearer token header. The token is used to authenticate and authorize access to the specified property.

If you issue a request using an expired token, an error is returned stating that the token is invalid. We recommended that you retrieve a new token several seconds before it expires to avoid any service disruption. (The expires_in attribute in the response indicates the number of seconds a token is valid.)

If you are calling the API from multiple servers, you can request a unique access token from each server and save it in memory. It is not necessary to persist the token to disk and attempt to reuse across all servers in your application. This should simplify your solution and is potentially more secure as the token is less likely to be compromised if it is not persisted to disk.

Obtaining an access token

To obtain an access token, complete these steps:

1. Obtain API credentials, which will be used to authenticate with the OAuth2 token service:

   • If you are an existing API partner, use your current API credentials to fetch the access token. You would usually use these credentials to access other APIs, such as Availability and Rates, Property, and Product. They are typically prefixed with ”EQC”.

     Note: If your password contains less than 16 characters, you must change your password. Passwords must contain at least 16 characters and include at least three of the following: uppercase letter, lowercase letter, a number, and a symbol. Passwords cannot contain these symbols: <, >, &, %, +, ', and "

   • If you are new partner, obtain Expedia credentials by submitting your request on this page.
     
     

   Ensure that these credentials are stored securely and are not exposed to your users through cookies, web storage, browser or mobile applications, and so on.

   Note: If you onboarded properties directly to Vrbo in addition to Expedia, you must obtain a separate token using your Vrbo credentials to use the API to issue requests based on Vrbo supplier IDs. The Expedia token can only be used to issue requests based on Expedia IDs.

2. Encode the username and password to Base64 by following the OAuth2 standard requirements.

3. Send a request to the OAuth2 token service (https://api.expediagroup.com/identity/oauth2/v3/token). The Content-Type header is required, and grant_type must be specified as a separate data parameter (shown below) or it must be included in the URL.

   Note that the access token's length may vary and additional attributes will be present in the response. Also, the expires_in attribute indicates how long the token is valid (in seconds). This value will change, so be sure to obtain the actual value of the field returned to you and use it to determine the expiration status of your token (and dynamically refresh the token based on expires_in).

4. Save the access token in a secure fashion (preferably in-memory), and do not expose the token to your users in any way. Do not attempt to parse the contents of the access token because they are subject to change. Always send the token directly to the API over a secure TLS connection using server-to-server communications.

Here is an example request to obtain a token:

curl -i -X POST https://api.expediagroup.com/identity/oauth2/v3/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic {base64_encoded_credentials}" \
  -d "grant_type=client_credentials"

Example response:

{
  "access_token": "oVapAccHHYCGzggNaVHP.ys7dffRkOP2om9Hkbylo.tssKms0UIo9KScLlegv1",
  "token_type": "bearer",
  "expires_in": 1799, 
  "scope": "lodging-supply.property-status.get"
}

Calling the API with an access token

After you obtain an access token, you must include it with all API requests; every request must be authenticated, no anonymous access is allowed. Pass the token in the header of requests as follows:

Authorization: Bearer {token}

If you have a valid token, your request is processed by the API. Otherwise, an error is generated indicating that the token has expired or is invalid in some way.

HTTP headers

Here are the request and response headers for calls made to the Lodging Supply GraphQL API.

Request headers

Response headers

Because the API is used over HTTP, standard headers that are part of the HTTP specification and industry standard extensions are returned as part of the response. However, be aware of the transaction-id response header, which provides a unique transaction ID generated by Expedia Group for all responses. Expedia Group recommends storing this identifier because it can be used to reference responses when troubleshooting GraphQL issues with Expedia Group.

Rate limits

The Lodging Supply GraphQL API has implemented request-based and operation-based rate limits, which prevent overuse of our services and ensure fair use by all partners so that we can maintain stability and optimal performance. We constantly evaluate API traffic as it surges and subsides, and we may adjust our rate limits as needed. Rate limits are enforced per connectivity partner:

• Request-based rate limit of 50 transaction-per-second (TPS). If exceeded, HTTP status code 429 is returned (no response body).

• Operation-based rate limits as shown in the table below. If exceeded, HTTP status code 200 is returned and an error message indicates the operation that exceed the limit.

  Operation	Rate limit
  property query (root level query for many operations, including property status)	Up to 150 TPS
  Compliance capability	registration query (under property:unitsPaginated) - Up to 30 TPS Up to 60 TPS for all other queries and mutations
  Messaging capability	Up to 45 TPS for each query and mutation
  Notifications (webhooks) service	Up to 10 TPS for each query and mutation
  Product management capability	Up to 10 TPS for each query and mutation
  Promotions capability	promotions query - Up to 20 TPS Up to 50 TPS for all other queries and mutations
  Reservations management capability	reservations query (under property) - Up to 30 TPS Up to 50 TPS for all other queries and mutations
  Reviews capability	Up to 50 TPS for each query and mutation

To avoid exceeding our rate limit, consider implementing the following strategies:

• Implement caching for read requests for data that does not change often. Store API responses locally and reuse them when possible.
• Spread out your requests over time instead of making them all at once. Running a large volume of closely-spaced requests can lead to rate limiting; try to control the request rate on the client side.
• Implement exponential backoff. If you receive a rate limit error, wait for a short time before retrying. Increase the waiting time exponentially for subsequent failures.
• Monitor your usage to keep track of how many requests you're making. Stay well below the limit to allow for unexpected spikes.
• Optimize your code to ensure you're not making unnecessary API calls.
• Schedule non-urgent tasks during off-peak hours for non-time-sensitive operations.

Testing requests and responses

We provide a graphical integrated development environment (IDE) that enables you to issue query requests using test data. This GraphQL explorer is available on many doc pages on this site. Here is the link.

Or, you can install a third-party IDE (desktop app), such as Prisma or Insomnia. After you install the application, configure it with either your client ID and secret or a token generated using these values. Refer to the application's documentation for more information about configuring authorization and headers. Then, load our GraphQL endpoint URL and issue test requests as needed.

Error handling

An error can occur during different phases of a GraphQL request (authentication, validation, schema generation, and execution). If an error occurs, an HTTP status code is returned as well as an error object. The HTTP status code of 200 is returned if a GraphQL execution error occurs, and a non-200 status code is returned if an HTTP or GraphQL request error occurs. For a list of HTTP status codes and GraphQL error classes, refer to Error handling.