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


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.


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.