The Booking Object¶

The booking object is the core data structure payload delivered in bookings.create webhook events. It provides a simplified and consolidated view of a booking, including passenger details, route information, and timing.

Fields¶

Field	Type	Description	Nullable
`contact_first_name`	string	First name of the primary contact.	No
`contact_last_name`	string	Last name of the primary contact.	No
`date_booked`	datetime	ISO 8601 timestamp of when the booking was created.	No
`date_paid`	datetime	ISO 8601 timestamp of when the booking was paid.	Yes
`status`	string	Current status of the booking (e.g., `CONFIRMED`, `PENDING`, `CANCELLED`).	No
`price`	integer	The purchase price of the booking.	Yes (if unconfigured)
`group_size`	integer	Total number of passengers (Adults + Children).	No
`departure_area`	string	Name of the departure area (e.g., "Bangkok").	Yes
`departure_area_id`	string	ID of the departure area (prefixed with `area_`).	Yes
`departure_station`	string	Name of the specific departure station/pier.	Yes
`departure_station_id`	string	ID of the departure station (prefixed with `stat_`).	Yes
`destination_area`	string	Name of the destination area.	Yes
`destination_area_id`	string	ID of the destination area (prefixed with `area_`).	Yes
`destination_station`	string	Name of the specific destination station/pier.	Yes
`destination_station_id`	string	ID of the destination station (prefixed with `stat_`).	Yes
`date_departure`	date	Date of departure (YYYY-MM-DD).	Yes
`time_departure`	time	Time of departure (HH:MM:SS).	Yes
`datetime_departure`	datetime	Full ISO 8601 departure timestamp.	Yes
`date_arrival`	date	Date of arrival (YYYY-MM-DD).	Yes
`time_arrival`	time	Time of arrival (HH:MM).	Yes
`datetime_arrival`	datetime	Full ISO 8601 arrival timestamp.	Yes
`route_name`	string	Descriptive name of the route.	Yes
`route_id`	string	ID of the route (prefixed with `rout_`).	Yes
`route_duration`	integer	Duration of the route in minutes.	Yes
`extra_params`	object	JSON object containing additional parameters.	Yes
`operator_code`	string	Booking reference code assigned by the operator.	Yes
`code`	string	TBT's unique booking reference code (prefixed with `book_`).	No

Nullable Fields Explanation¶

Several fields in the booking object may be null depending on the specific route configuration and the current status of the booking data:

price: May be null if the route pricing is dynamic, not yet fully configured, or pending calculation.
route_name: May be null if the associated route entry does not have a configured CMS title.
Timing Fields (date_departure, time_departure, datetime_departure, etc.): These rely on the scheduled_route configuration. If a schedule is incomplete or not linked correctly, these fields may be null.
Station/Area Fields: Dependent on the route's departure and destination linkage.
route_duration: May be null if the duration is not configured on the route.

Example JSON¶

{
  "contact_first_name": "John",
  "contact_last_name": "Doe",
  "date_booked": "2023-10-27T09:55:00Z",
  "date_paid": "2023-10-27T10:00:00Z",
  "departure_area": "Bangkok",
  "departure_area_id": "area_bkk",
  "departure_station": "Khaosan Road",
  "departure_station_id": "stat_khaosan",
  "destination_area": "Koh Tao",
  "destination_area_id": "area_kohtao",
  "destination_station": "Mae Haad Pier",
  "destination_station_id": "stat_maehaad",
  "status": "CONFIRMED",
  "price": 1500,
  "group_size": 2,
  "date_departure": "2023-10-28",
  "time_departure": "06:00:00",
  "datetime_departure": "2023-10-28T06:00:00",
  "date_arrival": "2023-10-28",
  "time_arrival": "14:00",
  "datetime_arrival": "2023-10-28T14:00:00",
  "route_name": "Bangkok -> Koh Tao",
  "route_id": "rout_bkk_kt",
  "route_duration": 480,
  "extra_params": null,
  "operator_code": "OP_CODE_123",
  "code": "BOOK_ID_123"
}