Track Endpoint

Capturing how your users interact with your platform is crucial for understanding their behavior and optimizing your sales. Our Track endpoint allows you to record key actions (events) that users perform on your website, such as purchase attempts or failed payments.

Based on our experience in the transportation industry, we have defined a relevant data schema for your business.

We process and store this information so you can easily visualize it in your Mixpanel dashboard or analyze it in detail using SQL queries, thus obtaining valuable insights for your business.

Events

Events are the way you can capture your users’ data. Currently, our Track endpoint supports the following events:

Name	Description	Purpose
Payment Failed	When the user attempts to complete the purchase but the payment fails.	It will allow you to understand the types of problems your users are facing when trying to complete the purchase.
Purchase Complete	When the user successfully completes the payment and their tickets are generated.	The most important information for your business, it’s a fundamental basis for comparing and understanding how to improve your sales.

Trip Schema

All events share a base schema for trip-related data. This schema corresponds to the trip field, which is an object with the following properties:

Field	Type	Required	Description
departure_arrival	string (date-time)	✓	Arrival date and time of the outbound trip in ISO 8601 format
departure_destination	string	✓	Destination city of the outbound trip
departure_destination_terminal	string	✓	Destination terminal of the outbound trip
departure_line	string	✓	Bus line for the outbound trip
departure_origin	string	✓	Origin city of the outbound trip
departure_origin_terminal	string	✓	Origin terminal of the outbound trip
departure_price	number	✓	Price of the outbound trip
departure_route	string	✓	Route of the outbound trip
departure_stop_cities	string	✓	Stop cities on the outbound trip, separated by commas
departure_stops	integer		Number of stops on the outbound trip
departure_time	string (date-time)	✓	Departure date and time of the outbound trip in ISO 8601 format
departure_transporter	string	✓	Transporter company for the outbound trip
discount_code	string		Discount code applied to the trip
recommended_trip	boolean		Indicates if it’s a recommended trip (valid only for recommendation service clients)
recommended_trip_type	string		Type of trip recommendation (valid only for recommendation service clients)
return_arrival	string (date-time)		Arrival date and time of the return trip in ISO 8601 format
return_destination	string		Destination city of the return trip
return_destination_terminal	string		Destination terminal of the return trip
return_line	string		Bus line for the return trip
return_origin	string		Origin city of the return trip
return_origin_terminal	string		Origin terminal of the return trip
return_price	number		Price of the return trip
return_route	string		Route of the return trip
return_stop_cities	string		Stop cities on the return trip, separated by commas
return_stops	integer		Number of stops on the return trip
return_time	string (date-time)		Departure date and time of the return trip in ISO 8601 format
return_transporter	string		Transporter company for the return trip

Event Schemas and Parameters

For each event, the object structure is as follows:

{
    "event_name": "payment_failed" | "purchase_complete",
    "event_data": {
        ...
        "product": "web" | "web-mobile" | "ios" | "android" | "ticket-office" | "travel-agency" | "call-center",
        "trips": [
            {
            ...
            },
        ]
        ...
    }
}

Additional fields specific to each event are added at the event_data level. The trips array contains a list of trip objects following the Trip schema fields.

Payment Failed

When a user attempts to complete the purchase but the payment fails, you’ll want to know the reasons why and the details of the chosen trip to help them complete the purchase.

Field	Type	Required	Description
agency_name	string		Name of the travel agency involved in the booking
coupon	string		Promotional coupon applied
discount_code	string		Discount code applied
distinct_id	string		Unique identifier for the user’s purchase attempt session
email	string		User’s email address in valid format
error_message	string		Error message provided by the payment engine
installments	integer		Number of installments selected for payment
insurance	boolean		Indicates if any type of insurance offered by your business was included
ip	string		User’s IP address (used for geolocation)
latitude	number		Latitude of the user’s location
longitude	number		Longitude of the user’s location
meta	object		Object where you can add any additional information you deem relevant
operation_id	string		Unique identifier for the booking operation
passenger_count	integer	✓	Total number of passengers
payment_card_affiliate	string		Payment card affiliation
payment_engine	string		Payment engine used
payment_type	string	✓	Selected payment type
phone	string		Phone number in E.164 format (e.g., +12125551234)
product	string	✓	Identifier of the product or sales channel
tickets	integer	✓	Total number of tickets
total	number	✓	Total amount of the booking
trips	array	✓	Array of trip objects
trips_count	integer	✓	Number of trips in the booking
user_fingerprint	string		Unique identifier of the user’s device
user_status	string		User status

Purchase Complete

When a user successfully completes the purchase, you’ll want to know the booking details to offer better experiences to your customers.

Field	Type	Required	Description
agency_name	string		Name of the travel agency involved in the booking
coupon	string		Promotional coupon applied
distinct_id	string		Unique identifier for the user’s purchase attempt session
email	string		User’s email address in valid format
insurance	boolean		Indicates if any type of insurance was included in the booking
ip	string		User’s IP address (used for geolocation)
latitude	number		Latitude of the user’s location
longitude	number		Longitude of the user’s location
meta	object		Object with additional event information
operation_id	string		Unique identifier for the booking operation
passenger_count	integer	✓	Total number of passengers
payment_card_affiliate	string		Payment card affiliation
payment_type	string	✓	Selected payment type
phone	string		Phone number in E.164 format (e.g., +12125551234)
product	string	✓	Identifier of the product or sales channel
tickets	integer	✓	Total number of tickets
total	number	✓	Total amount of the booking
trips	array	✓	Array of trip objects
trips_count	integer	✓	Number of trips in the booking
user_fingerprint	string		Unique identifier of the user’s device
user_status	string		User status

Field	Type	Required	Description
bus_categories	string	✓	Categories of the purchased tickets, comma-separated
departure_transport_type	string	✓	Transport type for the outbound trip
return_transport_type	string		Transport type for the return trip

Notes

Schema constraints are key to ensuring data integrity so you can gain the most relevant insights for your business.

If you are having trouble sending data, carefully review the error handling section.

Examples

Below are examples of how to send a Purchase Complete event to the Track endpoint using different programming languages.

curl \
-X POST '<BASE_URL>/datalake/track' \
-H 'Authorization: <Bearer_Token>' \
-H 'Origin: https://your-domain.com' \
-H 'Content-Type: application/json' \
-d '{
    "event_name": "purchase_complete",
    "event_data": {
        "passenger_count": 2,
        "payment_type": "credit_card",
        "trips_count": 1,
        "tickets": 2,
        "total": 31.00,
        "product": "web",
        "email": "john.doe@example.com",
        "phone": "+12154567890",
        "trips": [{
            "departure_arrival": "2025-04-25T10:30:00-05:00",
            "departure_destination": "Boston",
            "departure_destination_terminal": "South Station",
            "departure_line": "Coastal Express",
            "departure_origin": "New York",
            "departure_origin_terminal": "Port Authority",
            "departure_price": 15.50,
            "departure_route": "NY-BOS",
            "departure_stop_cities": "New Haven",
            "departure_stops": 1,
            "departure_time": "2025-04-25T15:30:00-05:00",
            "departure_transporter": "East Coast Bus Company",
            "bus_categories": "general",
            "departure_transport_type": "bus"
        }]
    }
}'

import requests

url = "<BASE_URL>/datalake/track"
headers = {
    'Authorization': '<Bearer_Token>',
    'Origin': 'https://your-domain.com'
}

payload = {
    "event_name": "purchase_complete",
    "event_data": {
        "passenger_count": 2,
        "payment_type": "credit_card",
        "trips_count": 1,
        "tickets": 2,
        "total": 31.00,
        "product": "web",
        "email": "john.doe@example.com",
        "phone": "+12154567890",
        "trips": [{
            "departure_arrival": "2025-04-25T10:30:00-05:00",
            "departure_destination": "Boston",
            "departure_destination_terminal": "South Station",
            "departure_line": "Coastal Express",
            "departure_origin": "New York",
            "departure_origin_terminal": "Port Authority",
            "departure_price": 15.50,
            "departure_route": "NY-BOS",
            "departure_stop_cities": "New Haven",
            "departure_stops": 1,
            "departure_time": "2025-04-25T15:30:00-05:00",
            "departure_transporter": "East Coast Bus Company",
            "bus_categories": "general",
            "departure_transport_type": "bus"
        }]
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const url = '<BASE_URL>/datalake/track';
const payload = {
    event_name: "purchase_complete",
    event_data: {
        passenger_count: 2,
        payment_type: "credit_card",
        trips_count: 1,
        tickets: 2,
        total: 31.00,
        product: "web",
        email: "john.doe@example.com",
        phone: "+12154567890",
        trips: [{
            departure_arrival: "2025-04-25T10:30:00-05:00",
            departure_destination: "Boston",
            departure_destination_terminal: "South Station",
            departure_line: "Coastal Express",
            departure_origin: "New York",
            departure_origin_terminal: "Port Authority",
            departure_price: 15.50,
            departure_route: "NY-BOS",
            departure_stop_cities: "New Haven",
            departure_stops: 1,
            departure_time: "2025-04-25T15:30:00-05:00",
            departure_transporter: "East Coast Bus Company",
            bus_categories: "general",
            departure_transport_type: "bus"
        }]
    }
};

fetch(url, {
    method: 'POST',
    headers: {
        'Authorization': '<Bearer_Token>',
        'Origin': 'https://your-domain.com',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

In this example:

A simple trip from New York to Boston is shown.
Required fields for the Purchase Complete event are included.
Additional required fields for each trip object (bus_categories and departure_transport_type) are added.

Responses

Successful Response

{
    "message": "Event success stored",
    "status": "success"
}

The successful response indicates that the event has been stored correctly and is being processed.

Error Response

In case of an error, you will find a list of reasons why the event could not be processed, as well as suggestions for correcting the problem. Refer to the errors section for more information on how to resolve the errors you encounter.