Constructing the request URL

The request URL—the URL that will return results from an attach module—consists of a domain, an endpoint, request parameters, and a signature parameter. This example shows a confirmed flight to LAX for 2 adults leaving January 2, 2023 and returning January 12, 2023 that was booked on November 12, 2022.

//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundStartDateTime=2023-01-02T11%3A55%3A00%2B08%3A00&outboundEndDateTime=2023-01-02T12%3A55%3A00%2B08%3A00&returnStartDateTime=2023-01-12T22%3A30%3A00%2B08%3A00&returnEndDateTime=2023-01-12T22%3A30%3A00%2B08%3A00&destinationTla=LAX&numOfAdults=2&locale=en-US&currencyCode=USD&bookingDateTime=2022-11-12T12%3A32%3A15%2B08%3A00&bookingId=123ABC&bookingStatus=confirmed&signature=bj01fgT85mUiRmzxxSufSmlGpiI

Constructing request parameters

In general, request parameters include details regarding the booked reservation, such as the destination and the trip start and end dates. This information is used to generate recommendations for the attach module. Some parameters are optional in a request, but some are required to return results.

Important

For security, ensure that all parameter values are percent-encoded UTF-8.

Available request parameters

Parameter	Description	Sample value	Required
`partnerId`	String value provided by Expedia that’s used to identify your organization in request parameters	partnername_hotel_conf_overlay	Yes
`bookingStatus`	String value that specifies the reservation status, which determines whether attach rates can be applied; if the booking status is pending or failed, no attach rates will be applied	confirmed	Yes
`bookingDateTime`	String value that specifies the date of the reservation; includes date, time, and time zone in ISO 8601 format	2024-08-29T05:54:02 Encoded value: 2024-08-29T05%3A54%3A02	Yes
`outboundEndDateTime`	String value that specifies the arrival at the destination; includes date, time, and time zone in ISO 8601 format	2024-08-29T05:54:02 Encoded value: 2024-08-29T05%3A54%3A02	Yes
`returnStartDateTime`	String value that specifies the departure from the destination; includes date, time, and time zone in ISO 8601 format Note: If unspecified, the default length of trip is 7 days	2024-08-29T05:54:02 Encoded value: 2024-08-29T05%3A54%3A02	—
`locale`	5-character string provided by Expedia that indicates the language in which the reservation was made	en-US	Yes
`currencyCode`	String provided by Expedia that indicates the currency in which the reservation was made	USD	Yes
`destinationTla`	3-character string indicating the International Air Transport Association (IATA) airport code for the destination Note: The request URL must include either this parameter (for bookings that include a flight) OR `latitude` and `longitude` (if no flight is included)	LAX	Yes
`latitude` and `longitude`	Float value of up to 12 decimals that specifies trip destination's coordinates Note: The request URL must include either this parameter (if no flight is included) OR `destinationTla` (for bookings that include a flight)	latitude=40.7141667 &longitude=-74.0063889	Yes
`signature`	27-character alphanumeric string value you’ll generate based on a secret key we provide See Building the request URL for more information	BcND1F7KElTyGtyUHeXHd2JJLFs	Yes
`numOfAdults`	Integer specifying the number of adults on the reservation; minimum 1	2	Yes
`numOfChildren`	Integer specifying the number of children on the reservation	3	—
`childAges`	Comma-delimited integer array specifying the ages of any children on the reservation; only required if `numOfChildren` is passed	5,4,2	Yes, if `numOfChildren` is passed

We’ve included some scenarios to help you understand the values for both straightforward and more complicated trips.

One-way trip example

As you might expect with a one-way trip, you would not be including the returnStartDateTime as part of the result parameter, so the default of 7 days will apply. For a direct one-way trip leaving Chicago on September 10, 2024 at 1:00 pm and arriving in Las Vegas the same day at 4:00 pm, the parameters might look like this:

bookingDateTime: 2024-09-01T05:54:02
origin: ORD
destinationTla: LAS
outboundStartDateTime: 2024-09-10T11:00:00
outboundEndDateTime: 2024-09-10T16:00:00
returnStartDateTime: 2024-09-17T12:00:00

//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundStartDateTime=2024-09-10T11%3A00%3A00&outboundEndDateTime=2024-09-10T16%3A00:00&returnStartDateTime=2024-09-17T12%3A00%3A00&origin=ORD&destinationTla=LAS&bookingDateTime=2024-09-01T05%3A54%3A02

Round trip example

A request for a direct round-trip booking to the same destinations, returning on September 14, 2024, might include parameters like this:

bookingDateTime: 2024-09-01T05:54:02
origin: ORD
destinationTla: LAS
outboundStartDateTime: 2024-09-10T11:00:00
outboundEndDateTime: 2024-09-10T16:00:00
returnStartDateTime: 2024-09-14T18:00:00

//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundStartDateTime=2024-09-10T11%3A00%3A00&outboundEndDateTime=2024-09-10T16%3A00%3A00&returnStartDateTime=2024-09-14T18%3A00%3A00&returnEndDateTime=2023-01-12T22%3A30%3A00%2B08%3A00&origin=ORD&destinationTla=LAX&bookingDateTime=2024-09-01T05%3A54%3A02

Multi-destination trip example

For a trip with multiple destinations, each leg will have different values for the outboundStartDateTime and outboundEndDateTime. A round-trip booking from Chicago to San Francisco with a stop in Las Vegas might look like this:

Leg 1: Chicago to Las Vegas

bookingDateTime: 2024-09-01T05:54:02
origin: ORD
destinationTla: LAS
outboundStartDateTime: 2024-09-10T11:05:00
outboundEndDateTime: 2024-09-10T16:17:00

Leg 2: Las Vegas to San Francisco

origin: LAS
destinationTla: SFO
outboundStartDateTime: 2024-09-12T13:27:00
outboundEndDateTime: 2024-09-12T16:10:00

Leg 3: San Francisco to Chicago

origin: SFO
destinationTla: ORD
outboundStartDateTime: 2024-09-14T16:15:00
outboundEndDateTime: 2024-09-14T20:22:00

//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundStartDateTime=2024-09-10T11%3A05%3A00&outboundEndDateTime=2024-09-10T16%3A17%3A00&origin=ORD&destinationTla=LAS&outboundStartDateTime=2024-09-12T13%3A27%3A00&outboundEndDateTime=2024-09-12T16%3A10%3A00&origin=LAS&destinationTla=SFO&outboundStartDateTime=2024-09-14T16%3A15%3A00&outboundEndDateTime=2024-09-14T20%3A22%3A00&origin=SFO&destinationTla=ORD&bookingDateTime=2024-09-01T05:54:02

Building the request URL

All request URLs will include the domain and endpoint followed by the request parameters, and will end with the signature generated with the secret key.

Secret key

A secret key is an alphanumeric string that is shared securely by Expedia and used to generate a signature that verifies the transaction. It will be 36 characters long, and it’s associated with the partnerId.

Note

Keep your secret key in a secure location and use it only for generating the signature. Do not pass the secret as a parameter during URL construction.

Domain, endpoint, and request parameters

Your request URL starts with the domain. We recommend that you keep the Expedia domain for request URLs protocol-agnostic: //xsell.expedia.com/. The next section of the URL is the request string, which consists of the case-sensitive endpoint /xsell-pwa.js? and the request parameters. Remember that the request parameters should be UTF-8 percent-encoded.

Step 1: Construct the request string

The request string includes the endpoint and request parameters (but not the domain). It should look something like this.

/xsell-pwa.js?partnerId=partner123&outboundStartDateTime=2024-10-22T11%3A55%3A00%2B08%3A00&outboundEndDateTime=2024-10-22T13%3A55%3A00%2B08%3A00&returnStartDateTime=2024-10-30T20%3A30%3A00%2B08%3A00&returnEndDateTime=2024-10-30T22%3A30%3A00%2B08%3A00&destinationTla=LAX&numOfAdults=2&locale=en-US&currencyCode=USD&bookingDateTime=2024-04-12T12%3A32%3A15%2B08%3A00&bookingId=123ABC&bookingStatus=confirmed

Step 2: Sign the request

The string obtained from Step 1 (including the leading /) should be signed with a hash-based message authentication algorithm (HMAC-SHA1) using the secret key shared by Expedia. In most cryptographic libraries, the resulting signature will be in binary format.

There are many implementations of this cryptographic hash function defined in the RFC 2104 for computer languages and frameworks. The available implementations include:

Step 3: Encode the resulting signature

Encode the binary signature using the modified Base64 for URLs, which replaces the + and / characters of the Base64 output with - (hyphen) and _ (underscore), respectively, to make it URL safe (see RFC 4648 for additional information). It should look similar to this:

bj01fgT85mUiRmzxxSufSmlGpiI

It’s also important to note that the padding = (if any) should be removed from the Base64 encoded string.

Step 4: Build the final request URL

Append the signature from step 3 to the string in step 1 as a signature parameter. The signature should always be the last parameter of the final request URL.

Prepend the protocol (// OR http:// OR https://) and domain (we recommend //xsell.expedia.com for protocol-agnostic URLs) to the resulting string.

//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundStartDateTime=2024-10-22T11%3A55%3A00%2B08%3A00&outboundEndDateTime=2024-10-22T13%3A55%3A00%2B08%3A00&returnStartDateTime=2024-10-30T20%3A30%3A00%2B08%3A00&returnEndDateTime=2024-10-30T22%3A30%3A00%2B08%3A00&destinationTla=LAX&numOfAdults=2&locale=en-US&currencyCode=USD&bookingDateTime=2024-04-12T12%3A32%3A15%2B08%3A00&bookingId=123ABC&bookingStatus=confirmed&signature=bj01fgT85mUiRmzxxSufSmlGpiI

Step 5: Add the JavaScript code

You’ll use the final request URL as the JavaScript src attribute on the page where the module should appear. For example:

<script src="//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundStartDateTime=2024-10-22T11%3A55%3A00%2B08%3A00&outboundEndDateTime=2024-10-22T13%3A55%3A00%2B08%3A00&returnStartDateTime=2024-10-30T20%3A30%3A00%2B08%3A00&returnEndDateTime=2024-10-30T22%3A30%3A00%2B08%3A00&destinationTla=LAX&numOfAdults=2&locale=en-US&currencyCode=USD&bookingDateTime=2024-04-12T12%3A32%3A15%2B08%3A00&bookingId=123ABC&bookingStatus=confirmed&signature=bj01fgT85mUiRmzxxSufSmlGpiI"></script>

Once you’ve created the request URL, you are ready to integrate it into your page code.