trivago Conversion API integration options

Conversion API v1: Notification API

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 in the deep-link. Required if not Click-in API is used string 74056p0c-g723-47ed-a38f-a900c56x0ecf true false false
advertiser_client_id Replacement for trv_reference when using Click-in API. It is required for all kind of notifications if Click-in API is used. 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.


Examples

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

    To simplify attribution of trivago-induced bookings and optimize campaign performance —particularly for CPA campaigns— the ADVERTISER must integrate the TRIVAGO conversion API and store the respective trv_reference in a 1st party cookie for 30 days. This ensures that sales and total gross booking value can be accurately attributed to trivago, even if a user leaves the booking funnel and returns within thirty (30) days of their initial click on the ADVERTISER's link from the TRIVAGO Platforms, in accordance with last-touch attribution.


    Conversion API v2: Click-in API

    To overcome issues with storing third-party cookies to keep state on the integrator side, Conversion Click-in API was introduced.

    The extended API provides a second endpoint "clickin". It has to be called on click-in on the integrator side. It expects an integrator generated advertiser_client_id together with the provided trv_reference and locale from the click-in URL.

    To notify about booking creation or changes, this advertiser_client_id has to be provided to the notification endpoint (see above) as the alternative to trv_reference.

    Endpoint "clickin"

    The endpoint for the trivago Conversion Click-in API in is:

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

    Supported methods


    Request Header

    The header needs to include two mandatory parameters:


    Key Description Format Sample Mandatory
    X-Trv-Ana-Key Universally unique identifier, 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. On click-in the advertiser should send a request to the mentioned endpoint including the trv_reference and locale (if present) as well as the advertiser_client_id. Specifically:


    Parameter Description Format Sample
    advertiser_id trivago's Advertiser ID, as defined and communicated to advertisers by trivago (always the same value for one advertiser). integer 123
    advertiser_client_id The identifier for that client on the advertiser side. The id has to be available later on when sending a booking confirmation as a replacement for trv_reference string it-is-advertiser-specific
    trv_reference Unique tracking parameter as provided at the end of the deep-link. string 74056p0c-g723-47ed-a38f-a900c56x0ecf
    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

    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.


    Examples

    Let's assume that the advertiser_id is 123.

    The deep link may look like:

    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&locale=DE

    The click-in should be sent via JSON POST request as follows:

    Endpoint:

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

    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,
"locale":"DE",
"advertiser_client_id":"its-handled-by-you"
}

    Response:

    {
 "state":"OK"
}