API of affiliate programs booking statistics

With the Travelpayouts API of affiliate programs booking statistics, you can retrieve data on bookings made through the affiliate programs you are connected to. This is useful for exporting data for analytics, automating reports, or tracking the performance of your tools.

When working with the API, you can specify which data to return, for which period, how to sort results, and more.

Access to the API

Access to Travelpayouts statistics API is granted to partners after registering on the platform.

To start, you’ll need an API token. You can find your token in your Travelpayouts account in Profile → API token.

Pass the token to the Header of the request in the X-Access-Token parameter.

Please note that API requests use limits, which are described in the article API rate limits.

Getting the list of available fields

First, you can get a list of all available fields and their types to form a request, using the following GET method:

https://api.travelpayouts.com/statistics/v1/get_fields_list

By default, the response returns raw fields.
To get aggregated fields, use the data_type parameter: GET https://api.travelpayouts.com/statistics/v1/get_fields_list?data_type=aggregated
You can also pass campaign_id=<id> to include program-specific fields.
For example, the Aviasales program: https://api.travelpayouts.com/statistics/v1/get_fields_list?campaign_id=100
In this case, you will also see fields like airline_code, airline_name, adults, children, etc.

Where to find a program ID. Open the program page in your Travelpayouts account; the numeric ID is in the URL (for example, https://app.travelpayouts.com/programs/100/about).

Example response with raw fields:

{
  "fields": [
    {
      "name": "action_id",
      "type": "string",
      "available_filters": ["eq", "ne"]
    },
    {
      "name": "action_type",
      "type": "string",
      "available_filters": ["eq", "ne"],
      "available_values": ["booking", "paid_click", "advertise_profit"]
    },
    {
      "name": "user_device_type",
      "type": "string",
      "available_filters": ["eq", "ne"]
    }
  ]
}

Getting data

Use the fields you discovered via get_fields_list to build a POST request to:

https://api.travelpayouts.com/statistics/v1/execute_query

The response will contain data for the affiliate program whose ID you pass in your filters. You can take the program ID from the program page URL in your Travelpayouts account (for example, https://www.travelpayouts.com/programs/84/about, where 84 is the Booking.com program ID).

Request body structure

The POST request body shall contain JSON structured in the following way:

fields — strings array comprised of the names of fields to be returned (from fields obtained in get_fields_list)
filters — filters of the request. Important note: date filter is mandatory. Each filter contains three fields:
- field — string referring to the field the filter will belong to
- op — operation to be conducted (list of available operations is returned by get_fields_list in available_filters) field:
  - eq — equality
  - ne — inequality
  - gt — greater
  - ge — greater than or equal
  - le — lower than or equal
  - lt — lower
  - in — any of the values
    Important: The in operator can only be used with fields that have a filled-in value in available_values (e.g. type and state)
- value — the value the operation will be applied to (some fields have a predefined set of available values returned by get_fields_list in available_values)
sort — sorting of the response
- field — string referring to the field used as a basis for data sorting in the response
- order — string referring to the order used as a basis for data sorting in the field:
  - asc — ascending sorting
  - desc — descending sorting
offset — offset (0 by default)
limit — number of entries (100 by default, maximum — 10,000).

Example 1. Basic request

{
  "fields": [
    "action_id",
    "external_click_id",
    "sub_id",
    "price_usd",
    "paid_profit_usd",
    "state",
    "date",
    "updated_at",
    "created_at"
  ],
  "filters": [
    {
      "field": "type",
      "op": "eq",
      "value": "action"
    },
    {
      "field": "campaign_id",
      "op": "eq",
      "value": 100
    },
    {
      "field": "date",
      "op": "ge",
      "value": "2025-06-22"
    }
  ],
  "sort": [
    {
      "field": "date",
      "order": "asc"
    }
  ],
  "offset": 0,
  "limit": 100
}

Response example

{
  "results": [
    {
      "action_id": "b91cb378-770e-55c7-b126d10",
      "created_at": "2025-06-23 13:43:30",
      "date": "2025-06-23",
      "external_click_id": "31130496725740",
      "paid_profit_eur": "47.14",
      "price_eur": "4288.00",
      "state": "paid",
      "sub_id": ".mobile_app_5f78c121aea424a64",
      "updated_at": "2025-06-24 10:28:44"
    }
  ],
  "fields": [
    "action_id",
    "external_click_id",
    "sub_id",
    "price_eur",
    "paid_profit_eur",
    "state",
    "date",
    "updated_at",
    "created_at"
  ],
  "filters": [
    {
      "field": "type",
      "op": "eq",
      "value": "action"
    },
    {
      "field": "campaign_id",
      "op": "eq",
      "value": 100
    },
    {
      "field": "date",
      "op": "ge",
      "value": "2025-06-22"
    }
  ],
  "sort": [
    {
      "field": "date",
      "order": "asc"
    }
  ],
  "total_rows": 40,
  "offset": 0,
  "limit": 1
}

Response fields

action_id — unique identifier of the action (booking or order)
external_click_id — ID of the click that led to the action
sub_id — SubID, if it was specified when creating the affiliate tool
price_eur — order amount in the specified currency
paid_profit_eur — confirmed earnings in the specified currency
state — status of the action: e.g., paid — confirmed, pending — in progress, canceled — canceled
date — date of the action (usually the booking or purchase date)
updated_at — date and time of the last update of the action data
created_at — date and time when the action record was created in the system

Service fields

fields — list of fields that were requested and returned in the response
filters — filters applied when retrieving the data
sort — sorting rule (by which field and in what order)
total_rows — total number of records matching the query criteria
offset — number of skipped records (e.g., for pagination)
limit — number of records returned in the response (selection limit)

Example 2. Request with grouping

{
  "fields": [
    "user_device_type",
    "inits_count",
    "searches_count",
    "redirects_count",
    "processing_actions_count",
    "cancelled_actions_count",
    "paid_actions_count",
    "paid_profit_eur_sum",
    "processing_profit_eur_sum"
  ],
  "filters": [
    {
      "field": "date",
      "op": "ge",
      "value": "2020-01-30"
    },
    {
      "field": "date",
      "op": "le",
      "value": "2020-01-30"
    },
    {
      "field": "campaign_id",
      "op": "eq",
      "value": 100
    }
  ],
  "group": ["user_device_type"],
  "offset": 0,
  "limit": 100
}

Response example

{
  "results": [
    {
      "cancelled_actions_count": 44,
      "redirect_count": 8312,
      "inits_count": 11642,
      "paid_actions_count": 303,
      "paid_profit_eur_sum": "557.37788661",
      "processing_actions_count": 0,
      "processing_profit_eur_sum": "0.00000000000000",
      "searches_count": 48987,
      "user_device_type": "Desktop"
    }
  ],
  "fields": [
    "user_device_type",
    "inits_count",
    "searches_count",
    "redirect_count",
    "processing_actions_count",
    "cancelled_actions_count",
    "paid_actions_count",
    "paid_profit_eur_sum",
    "processing_profit_eur_sum"
  ],
  "filters": [
    {
      "field": "date",
      "op": "ge",
      "value": "2020-01-30"
    },
    {
      "field": "date",
      "op": "le",
      "value": "2020-01-30"
    },
    {
      "field": "campaign_id",
      "op": "eq",
      "value": 100
    }
  ],
  "group": ["user_device_type"],
  "offset": 0,
  "limit": 100
}

Response fields

cancelled_actions_count — number of canceled bookings
redirect_count — number of clicks on partner tools
inits_count — number of widget initializations
paid_actions_count — number of paid bookings/orders
paid_profit_eur_sum — income obtained, in the selected currency
processing_actions_count — number of processing bookings/orders
processing_profit_eur_sum — income amount in the selected currency for processing bookings/orders (potential income)
searches_count — number of searches
user_device_type — the type of device used by users for an action (search, booking or order)
created_at — the date when the booking was made
filters — filters used
group — selected grouping type
offset — number of missed database entries
limit — number of shown database entries.

Tips for using filters

The speed of query execution depends directly on the set of filters passed. The stricter they are, the faster you will get your data.

The most important filters affecting the speed:

date — filter by date. The wider the date range, the slower the query will be executed, try not to specify large ranges unnecessarily.
type — event type. If you know exactly what types of data you want to get, you should definitely add this filter
state — event status, works only for type = action|referral, if you are requesting data on these types of events and you know exactly what state you need the data in — be sure to add this filter.

Examples of optimal filters for different cases

I want to see when the booking was made.

To include the booking date in the API response, you need to explicitly specify the created_at field in the fields array:

{
  "fields": ["paid_profit_rub_sum", "created_at"],
  "filters": [
    {
      "field": "date",
      "op": "ge",
      "value": "2025-05-01"
    }
  ]
}

The created_at field returns the date the booking was created and can be useful for tracking user activity.

I want to get the number of widget initializations for June 2025.

Here we need a filter by dates and also event type and we are only interested in init:

[{"field":"date","op":"ge","value":"2025-06-01"},{"field":"date","op":"lt","value":"2025-07-01"},{"field":"type","op":"eq","value":"init"}]

I want to get the total number of bookings for July 2023.

In this case, it is best to apply a filter by type with the in operator, and include action and referral:

[{"field":"date","op":"ge","value":"2023-07-01"},{"field":"date","op":"lt","value":"2023-08-01"},{"field":"type","op":"in","value":["action", "referral"]}]

I want to get the number of paid bookings, not including referral bookings, for August 2023.

Here you need to apply not only a filter by type equal to action, but also a filter by state (we are interested only in paid bookings):

[{"field":"date","op":"ge","value":"2023-08-01"},{"field":"date","op":"lt","value":"2023-09-01"},{"field":"type","op":"eq","value":"action"},{"field":"state","op":"eq","value":"paid"}]

I want to get the sum of paid bookings in currency X for August 2023.

We only pay for bookings and referral actions, which means in this case we need a filter by event type equal to action or referral, plus a filter by event state (we are only interested in paid ones). In the end, the filters for this case will be identical to the case above:

[{"field":"date","op":"ge","value":"2023-08-01"},{"field":"date","op":"lt","value":"2023-09-01"},{"field":"type","op":"eq","value":"action"},{"field":"state","op":"eq","value":"paid"}]