trivago Conversion API integration

To be able to view the conversion rate of clicks coming from trivago in trivago Intelligence, it's highly recommended to integrate one of our trivago conversion tracking solutions. In this page you will find all the necessary instructions to integrate our Conversion API.

Endpoint

The endpoint for the trivago Conversion API is:

https://secde.trivago.com/tracking/booking

Supported methods

POST: booking confirmation
DELETE: booking cancellation
PUT: booking update

Request Header

The header needs to include 2 mandatory parameters:

Key	Description	Format	Sample	Mandatory
`X-Trv-Ana-Key`	Universally unique idenfitier, shared with you by your Technical Account Manager.	string	bf5bead6-222d-4dcd-b943-7f8fdf4a339b	true
`Content-Type`	The format of your request, which needs to be given as JSON data	string	application/json	true

Request Body

The request body has to be given as JSON data.

trivago will append a parameter called trv_reference to the end of the deep-link. This parameter is a unique value. As soon as the booking is confirmed, the advertiser should send a request to the above-mentioned endpoint including the same trv_reference as well as the other mandatory parameters. Specifically:

Parameter	Description	Format	Sample	Mandatory POST	Mandatory DELETE	Mandatory PUT
`trv_reference`	Unique tracking parameter as provided at the end of the deep-link.	string	74056p0c-g723-47ed-a38f-a900c56x0ecf	true	false	false
`advertiser_id`	trivago's Advertiser ID, as defined and communicated to advertisers by trivago (always the same value for one advertiser).	integer	123	true	true	true
`hotel`	The advertiser's unique hotel ID for the booked hotel. Must be identical to the IDs used in the inventory feed.	string	HOTEL537	true	true	true
`arrival`	Arrival date	UNIX timestamp	1524566908	true	true	true
`departure`	Departure date	UNIX timestamp	1524739708	true	true	true
`date_format`	If `arrival` and `departure` cannot be given in UNIX timestamp format, they can be given in a different format (e.g. 20181025 - Ymd). In this case, the `date_format` parameter has to be provided. The recommended format is Ymd but the separator can be adjusted as desired, according to the accepted formats. Please note that the date should be shared in UTC. If not possible, the utc-based timestamp needs to be included in both booking_date and booking_date_format (e.g. "booking_date_format":"YmdHisP", "booking_date":"20200929123015+07:00").	string	Ymd	true if `arrival` and `departure` are not provided in UNIX timestamp	true if `arrival` and `departure` are not provided in UNIX timestamp	true if `arrival` and `departure` are not provided in UNIX timestamp
`booking_date`	Booking submit date	UNIX timestamp	1524566500	true	true	true
`booking_date_format`	If `booking_date` cannot be given in UNIX timestamp format, it can be given in a different format. In this case, the `booking_date_format` parameter has to be provided. Please also include the time of the booking in seconds (e.g. 20201025173002). The recommended format is YmdHis but the separator can be adjusted as desired according to the accepted formats. Please note that the date should be shared in UTC. If not possible, the utc-based timestamp needs to be included in both `booking_date` and `booking_date_format` (e.g. "booking_date_format":"YmdHisP", "booking_date":"20200929123015+07:00").	string	YmdHis	true if `booking_date` is not provided in UNIX timestamp	true if `booking_date` is not provided in UNIX timestamp	true if `booking_date` is not provided in UNIX timestamp
`volume`	Total gross booking price per stay (including all rooms, all nights). Gross = net rate + booking fee + VAT.	float	150.70	true	true	true
`currency`	Currency in ISO 4217 code.	string	USD	true	true	true
`booking_id`	The advertiser's booking reference.	string	AC500	true	true	true
`locale`	Contains the trivago POS the user clicked from, before being redirected to the advertiser's site. Please refer to the following page for all available and expected codes. In case you need to append the identifier to the deep links, please approach your Technical Account Manager.	string	US	true	true	true
`number_of_rooms`	The total amount of rooms booked with the same booking_id.	integer	2	true	true	true
`margin`	Percentage which is received from the booking amount of the hotel as commission for the booking (in this sample case 15.8%).	float	15.8	false	false	false
`margin_absolute`	In case the margin cannot be provided in percentage, it can be provided alternatively as absolute value (in this example 60.30 USD). Please note that the currency of `margin_absolute` should match the `currency` provided for the `volume`.	float	60.30	false	false	false
`refund_amount`	Total refunded price per stay (including all rooms, all nights, all fees). The parameter is mandatory for DELETE calls even if `refund_ratio` is provided.	float	125	false	true	false
`refund_ratio`	It specifies how much of a given `volume` is going to be refunded. It needs to be shared with 4 decimal places (e.g.:1.0000=100%, 0.0000=0.00%, 0.5052=50.52%)	float	0.5000	false	false	false
`cancellation_date`	Cancellation submit date.	UNIX timestamp	1591783200	false	true	false
`cancellation_date_format`	If `cancellation_date` cannot be given in UNIX timestamp format, it can be given in a different format. In this case, the `cancellation_date_format` parameter has to be provided. Please also include the time of the cancellation in seconds (e.g. 20201025173002). The recommended format is YmdHis but the separator can be adjusted as desired according to the accepted formats. Please note that the date should be shared in UTC. If not possible, the utc-based timestamp needs to be included in both `cancellation_date` and `cancellation_date_format` (e.g. "cancellation_date_format":"YmdHisP", "cancellation_date":"20200929123015+07:00").	string	YmdHis	false	true if `cancellation_date` is not provided in UNIX timestamp	false
`update_date`	Booking update date.	UNIX timestamp	1591783603	false	false	true
`update_date_format`	If `update_date` cannot be given in UNIX timestamp format, it can be given in a different format. In this case, the `update_date_format` parameter has to be provided. Please also include the time of the cancellation in seconds (e.g. 20201025173002). The recommended format is YmdHis but the separator can be adjusted as desired according to the accepted formats. Please note that the date should be shared in UTC. If not possible, the utc-based timestamp needs to be included in both `update_date` and `update_date_format` (e.g. "update_date_format":"YmdHisP", "update_date":"20200929123015+07:00").	string	YmdHis	false	false	true if `update_date` is not provided in UNIX timestamp
`update_origin`	Describes whether a PUT call is based on an user's or an advertiser's update to given booking confirmation data. The possible values are either "advertiser" or "user".	string	advertiser user	false	false	true

Response

All requests will return a JSON formatted response containing a state ("OK" or "FAILED") and an optional errorMessage if state is "FAILED".

Ok-Response (response code 2xx)

{
"state":"OK"
}

Error-Response (all other response codes)

{
"state":"FAILED",
"errorMessage":"Error in trv_reference: invalid"
}

Response codes

To allow callers more precise reaction on invalid requests responses multiple response codes are used to differentiate between errors causing that request to fail. All 4xx response codes indicating issues in the request which can only be fixed on caller side. Check errorMessage in the response property for more details.

200: Ok - Request processed successfully
202: Accepted - Request processed successfully but had warnings (invalid locale)
400: Bad Request - The request is not processable at all
403: Forbidden - The API key is missing or invalid
404: Not Found - The request URL does not exists
422: Unprocessable Entity - Request validation could not be passed because of invalid request data (missing values, invalid format, etc.)
500: Internal Server Error - Returned on any unexpected behaviour during processing. Could an implementation issue or is related to any temporary error conditions like unavailable resources.

Samples

Let's assume that the advertiser_id is 123. For a booking for the property with hotel "MUC1345" on trivago.de, from 24th to 25th of April 2020 for 250.50 EUR, the advertiser receives a margin of 14.5% on this hotel and the booking_id is "AC500".

First of all, the deep-link will include a trv_reference:

https://advertiser-site.com/MUC1345/Executive_Double?start_date=2020-04-24&end_date=2020-04-25&num_adults=2&trv_reference=74056p0c-g723-47ed-a38f-a900c56x0ecf

The booking confirmation should be sent via JSON POST request as follows:

Endpoint:

https://secde.trivago.com/tracking/booking

POST Request Header:

Content-Type: application/json
X-Trv-Ana-Key: bf5bead6-222d-4dcd-b943-7f8fdf4a339b

POST Request Body:

{
"trv_reference":"74056p0c-g723-47ed-a38f-a900c56x0ecf",
"advertiser_id":123,
"hotel":"MUC1345",
"arrival":"20200424",
"departure":"20200425",
"date_format":"Ymd", 
"volume":250.50,
"locale":"DE",
"booking_id":"AC500",
"margin":14.5,
"currency":"EUR",
"booking_date":"20190919092356+07:00", 
"booking_date_format":"YmdHisP",
"number_of_rooms":2
}

Response:

{
 "state":"OK"
}

In case, later on, the same booking is changed by the user, the advertiser can also send a booking update request to the same endpoint:

PUT Request Header:

Content-Type: application/json
X-Trv-Ana-Key: bf5bead6-222d-4dcd-b943-7f8fdf4a339b

PUT Request Body:

{
 "trv_reference":"74056p0c-g723-47ed-a38f-a900c56x0ecf",
 "advertiser_id":123,
 "hotel":"MUC1345",
 "arrival":"20200424",
 "departure":"20200425",
 "date_format":"Ymd", 
 "volume":250.50,
 "locale":"DE",
 "booking_id":"AC500",
 "margin":14.5,
 "currency":"EUR",
 "booking_date":"20190919092356",
 "booking_date_format":"YmdHis",
 "number_of_rooms":2,
 "update_date":"20200219092050",
 "update_date_format":"YmdHis",
 "update_origin":"user"
}

Response:

{
 "state":"OK"
}

If eventually the same booking is cancelled, the advertiser can also send a booking cancellation request to the same endpoint:

DELETE Request Header:

Content-Type: application/json
X-Trv-Ana-Key: bf5bead6-222d-4dcd-b943-7f8fdf4a339b

DELETE Request Body:

{
"trv_reference":"74056p0c-g723-47ed-a38f-a900c56x0ecf",
"advertiser_id":123,
"hotel":"MUC1345",
"arrival":"20200424",
"departure":"20200425",
"date_format":"Ymd", 
"volume":250.50,
"locale":"DE",
"booking_id":"AC500",
"margin":14.5,
"currency":"EUR",
"refund_amount":250.50,
"refund_ratio":"1.0000",
"booking_date":"20190919092356",
"booking_date_format":"YmdHis",
"number_of_rooms":2,
"cancellation_date":"20200219092050",
"cancellation_date_format":"YmdHis"
}

Response:

{
 "state":"OK"
}

Accepted Date / Time formats

The following pattern characters are supported:

Y - year in 4 digits (e.g. "2021")

m - month in 2 digits (e.g. "01" for January)

d - day of the month in 2 digits (e.g. "21")

H - hour in 2 digits, in 24hours format (e.g. "16" for 4pm)

i - minutes in 2 digits (e.g. "20")

s - seconds in 2 digits (e.g. "06")

P - timezone offset with "+/-hour:minute". Hour and minutes need to include 2 digits each (e.g. "+02:00")

U - if dates are provided in Unix timestamp, U can be used as value for the related date format parameter

Separators can be optionally used between the pattern characters. The following separators are supported:

. - dot

, - comma

- blank space

/ - slash

: - colon

- - minus (please keep in mind this might cause issues if used together with P and +/- timezones)

Attribution

In order to simplify attribution of trivago induced bookings, the respective trv_reference must be stored for 30 days using a cookie. This assures that conversion data can still be attributed to trivago in case the user leaves the booking funnel and returns to the page later to complete the booking.