Brands Technical Integration with Travelpayouts

Have you already registered on our platform and studied the main article? The next step is technical integration to run your program. It is required to link the users' bookings on your resource to the partners who brought them.

There are different ways of integration, but we use the most reliable and convenient one — integration via API. This article contains information about the integration process.

How is the transition to the brand’s website tracked?

Each transition is carried out with a specific label. With its help, you can separate the traffic coming from the Travelpayouts from any other. You can take any label you like — the decision is yours. The utm_source=TO is the most commonly used one.

You can find the information on how to put and analyze labels in the following article: How to make a UTM tag correctly.

At each transition, you must accept an additional parameter from Travelpayouts, which always contains a unique value for the transition. This parameter is necessary to link bookings, clicks and partners in our booking accounting system.

The name of this parameter is determined by you. Typically, our brands use track_id. The value of this parameter is a line containing Latin letters, numbers and dashes. The parameter length is 32 characters. Example: 32990942748b4e5db9e8096127-79430. However, if possible, it is better to support 64 characters.

With each transition, you need to write the parameter value to the cookie file, for the period specified in the contract. If a user goes directly to your website during this time and books a travel service, then along with the booking information, you must save the track_id parameter, which was transmitted to you at the time of the user’s last click. Code examples for writing a parameter to a cookie can be viewed in your Travelpayouts dashboard, in the Integration section.

How is the booking information collected?

In order for us to link bookings to partners, you need to transmit a certain set of data in JSON format to Travelpayouts information.

The information must be accessed via a direct URL without the need for authorization. If preferred, an option with the transfer of the key/token in the request is possible.

We should be able to set the data upload period in the request. The parameters should be named from and to. Their format is YYYY-MM-DD. For example, "from=2021-10-01&to=2021-10-20" will upload all bookings that have changed during this period.

Required data in the upload:

  • order_number — is a unique order number in your system;
  • price — is the full cost of the booking, from which we consider the partner’s remuneration along with Travelpayouts remuneration if we work with you according to the Application Cost scheme;
  • base_profit — is the value from which the partner’s remuneration and Travelpayouts remuneration are calculated if we work with you according to the Advertiser’s Income scheme;
  • profit — full remuneration of the partner and Travelpayouts. The amount that will be included in the invoice;
  • currency — the code of the currency in which the price and profit data are displayed (EUR, USD, etc.);
  • description — description of the order that the partner will see. It is necessary to use a nested structure to describe all the details of the order, for example:
    {checkin_date: "2021-10-01", checkout_date: "2021-10-05", country: "France", city: "Paris", property_name: "Ritz Paris", guests_count: "2"}
    If the amount of the reward depends on the booking parameters, specify these parameters in this block. Any other information that will help our partners better understand the conversion is also indicated here.
    You must send all information about the order without disclosing the user’s personal data. Minimum information: dates, cities and countries of entry/exit. If you have several types of products, then you also need to specify the type: tours, buses, excursions, transfers, etc.
    We will carefully sort the data into parameters and show it to the partner in your personal account. This information is very useful; therefore, it’s worth transmitting as much data as possible.
    For example:
  • track_id — is a parameter that is passed by us when a user navigates to your resource (example: track_id=32990942748b4e5db9e8096127-79430);
  • status — is the booking status:
    • processing — the booking has been created, but has not been paid or confirmed yet. The funds have not been credited to the partner yet, but he sees the booking in his affiliate dashboard;
    • paid— the booking is paid, the funds are credited to our partner. You guarantee payment of the booking fee;
    • cancelled — the booking has been cancelled completely, the funds have been debited from our partner’s balance. You don’t have to pay us for this booking;
  • updated_at — is the date of the last reservation change. If the status, cost, income, or other data has changed, the updated_at parameter must contain the date and time of the change.

All bookings in the upload are sorted by the updated_at parameter from the smallest to the largest.

Thus, any booking change will be taken into account, including any refunds, etc.

Example of uploading one of our brands:

[
   {
      "order_number": 8717,
      "price": "500.0",
      "profit": "40.0",
      "currency": "usd",
      "description": {
         checkin_date: "2018-01-01",
         checkout_date: "2018-01-10",
         city: "Paris",
         property_name: "Ritz Paris, Paris",
         guests_count: "2"
      },
      "track_id": "32990942748b4e5db9e8096127-79430";
      "status": "processing",
      "updated_at":"2017-02-15T16:36:40"
   }
]

Please pay attention to the status parameter. As a brand, you only pay for bookings that have switched to the Paid status. If the booking has been cancelled (Cancelled status) or the date of its holding has not yet arrived (Processing status), it does not get into your monthly bill for payment.

Short summary

As a result of the integration, two links are required from you:

  1. A link to your website with tracking parameters. For example, https://www.advertiser.com/?utm_source=Travelpayouts&track_id=XXXX (as mentioned above, you define the names of variables for these parameters yourself).
  2. Link to booking statistics.

After we receive the links from you, we will make a test purchase and make sure that all the data is displayed in the statistics.