home > support > API > Marketplace API > API: search bookings

Search Bookings

Allows searching by several criteria, returns just a basic overview of each booking. For more detail on a particular booking see Show booking.

REST info

Endpoint/p/bookings/search
/c/bookings/search
FormatsXML
Example/p/bookings/search.xml?page=2&per_page=20
VerbGET

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object search_bookings ( [ string $params = "" [, int $channel = 0 ]] )


Parameters

$params
Search querystring, see possible values in the table below
$channel
Channel to search, 0/blank for all connected channels

Example

// Tour Operators set their channel here
// Marketplace Partners can optionally set the Channel ID
// Here we set to 0 for all connected channels
$channel = 0;

// Optionally define search parameters
// Here we are just returning active (not cancelled / expired) bookings
$params = "active=1";

// Query the TourCMS API
$result = $tourcms->search_bookings($params, $channel);

// Loop through each booking
foreach($results->booking as $booking) {
  // Print out the booking ID and channel name
  print $booking->booking_id." - ".$booking->channel_name." > ";

  // Print out the booking name and revenue
  print $booking->booking_name." (".$booking->sales_revenue_display.")";
  print "<br />";
}
12345 - Example Tours > Highland Walk (£599.00)
99281 - Adventure Co > Half day rafting (£99.00)

C# examples use the .Net Client Library

Overload list

XmlDocument SearchBookings ()
XmlDocument SearchBookings (string queryString)
XmlDocument SearchBookings (string queryString, int channelId)


Parameters

queryString
Optional, filter by querystring (see table of parameters below)
channelId
Optional, bookings from a single channel

Example

// Optionally set the Channel ID
// Here we set to 0 for all connected channels
int channelId = 0;

// Optionally define search parameters
// Here we are just returning active (not cancelled / expired) bookings
string queryString = "active=1";

// Query the TourCMS API
XmlDocument doc = myTourCMS.SearchBookings(queryString, channelId);

// Display Booking list
XmlNodeList bookingList = doc.GetElementsByTagName("booking");
foreach (XmlNode booking in bookingList)
{
 // Booking ID
 string bId = booking.SelectSingleNode("booking_id").InnerText;
 // Channel Name
 string cName = booking.SelectSingleNode("channel_name").InnerText
 // Booking Name
 string bName = booking.SelectSingleNode("booking_name").InnerText
 // Booking Revenue
 string bRev = booking.SelectSingleNode("sales_revenue_display").InnerText

 Console.WriteLine(bId + " " + cName + " - " + bName + "(" + bRev + ")");
} 
12345 Example Tours - Highland Walk (£599.00)
99281 Adventure Co - Half day rafting (£99.00)

VB examples use the .Net Client Library

Overload list

XmlDocument SearchBookings ()
XmlDocument SearchBookings (String queryString)
XmlDocument SearchBookings (String queryString, Integer channelId)


Parameters

queryString
Optional, filter by querystring (see table of parameters below)
channelId
Optional, bookings from a single channel

Example

' Optionally set the Channel ID
' Here we set to 0 for all connected channels
Dim channelId As Integer = 0

' Optionally define search parameters
' Here we are just returning active (not cancelled / expired) bookings
Dim queryString As String = "active=1"

' Query the TourCMS API
Dim doc As XmlDocument = myTourCMS.SearchBookings(queryString, channelId)

' Display Booking list
Dim bookingList As XmlNodeList = doc.GetElementsByTagName("booking")

For Each booking As XmlNode In bookingList
{
 ' Booking ID
 Dim bId As String = booking.SelectSingleNode("booking_id").InnerText
 ' Channel Name
 Dim cName As String = booking.SelectSingleNode("channel_name").InnerText
 ' Booking Name
 Dim bName As String = booking.SelectSingleNode("booking_name").InnerText
 ' Booking Revenue
 Dim bRev As String = booking.SelectSingleNode("sales_revenue_display").InnerText

 Console.WriteLine(bId & " " & cName & " - " & bName & "(" & bRev & ")")
} 
12345 Example Tours - Highland Walk (£599.00)
99281 Adventure Co - Half day rafting (£99.00)

NodeJS examples use the NodeJS Wrapper


Example

// Search for bookings made in the first two weeks of January 2016.
TourCMS.searchBookings({
	channelId: 3930,
	qs: {
		made_date_start: "2016-01-01",
		made_date_end: "2016-01-14"
	},
	callback: function(response) {
		response.booking.forEach(function(booking) {
			console.log(booking.booking_id)
		})
	}
});
1234
1235

Looking for sample code in a different language? TourCMS and community provided API libraries

Querystring parameters

Querystring parameters
ParameterNotes
made_date_start
made_date_end
Use these two parameters to specify a range of booking dates to search, so for example you could search for just the bookings made in the last 24 hours. Note this is the date the booking was created and not the date of travel. YYYY-MM-DD
 
If used these MUST be used as a pair
start_date_start
start_date_end
Use these two parameters to specify a range of booking dates to search, so for example you could search for just the bookings arriving today. NOTE that if the booking has tours for today AND tours for tomorrow on the same booking, the start date (for the booking) will be TODAY. YYYY-MM-DD
 
If used these MUST be used as a pair
end_date_start
end_date_end
Use these two parameters to specify a range of booking dates to search, so for example you could search for just the bookings ending today. NOTE that if the booking has tours for today AND tours for tomorrow on the same booking, the end date (for the booking) will be TOMORROW. YYYY-MM-DD
 
If used these MUST be used as a pair
component_start_dateFind bookings with a tour/transfer on a particular date YYYY-MM-DD
activePass in a value of 1 to exclude cancelled or expired bookings (bookings may be quotes that weren't taken up by the customer and subsequently expire), 0 to just return cancelled or expired bookings.

Leave blank / don't supply to return active & inactive bookings
final_checkPass in a value of 1 to only return bookings that HAVE had their final check completed, 0 to return only bookings that HAVE NOT had their final check completed.
 
Leave blank / don't supply to return all bookings regardless of final check status (default).
lead_customer_surnameLead customer surname (part matches also checked)
lead_customer_surname_startLead customer surname (part matches ony from the start of the surname, e.g. 'kha' would match 'Khan' but not 'Beckham')
lead_customer_emailLead customer email address (part matches also checked)
lead_customer_telLead customer telephone, matches home, work, sms, mobile (part matches also checked)
tour_idTour ID. Individual or comma separated list. E.g 1,2,3
Combine with List Product Filters to list bookings for tours in a product filter.
channel_id_tour_idChannel ID & Tour ID, for use by Agents search over multiple Channels. Individual or comma separated list. E.g 3930_1,3930_2,1234_3
Combine with List Product Filters to list bookings for tours in a product filter.
booking_nameBooking name (part matches also checked) (Often the main tour name becomes the booking name)
customer_idUse to search for bookings by a specific customer, only works if the channel ID is also supplied (channel id is passed in the header if calling the API directly or as the second parameter if using the PHP/.Net API wrappers). Currently searches the lead customer only
per_pageNumber of results to return per page. Max is 500.
pageInteger for which page number to return. Default is page 1

Results order

If you send active=0 the results order will be most recently cancelled booking first otherwise the default will be to list most recently received booking first

Response fields

Response fields
XML NodeNotes
request Confirmation of the request that you sent
error Any error message returned, if there is no error this will just contain the text OK
total_bookings_count Total number of bookings returned by the search (i.e. not just the number on this page)
total_bookings_quotprov Total number of bookings that are at the "Quotation" or "Provisional" status
total_bookings_canc Total number of bookings that are cancelled
total_bookings_conf Total number of confirmed bookings
booking

There will be one booking node for each result on this page.

Each booking node contains the following child nodes.

XML NodeNotes
booking_idID number for the booking, will be unique per channel but not unique accross all channels
channel_idChannel ID
account_idAccount ID
channel_nameName of the channel the booking is with (e.g. "Example Tours")
made_date_timeDate/Time the booking was made.
E.g. 2010-06-28 14:45:53
start_dateDate the booking starts. YYYY-DD-MM.
end_dateDate the booking ends. YYYY-DD-MM.
booking_nameThe name of the booking, generally named after the primary product on a booking however may be renamed or reference a Tailor made itinerary
booking_name_customIf a custom booking name has been set it will be returned here (and will also be returned in <booking_name>) otherwise blank
statusStatus of the booking
 
0 - Quote
1 - Provisional
2 - Confirmed
3 - Confirmed & archived
 

NB: If cancel_reason reason is set then the booking may be cancelled, for example it's possible to have a "Provisional" booking that is cancelled. You must check that cancel_reason is 0 if you want to ensure the booking is not cancelled
status_textTextual representation of the booking status.
E.g. "Confirmed (A)"
cancel_reasonIf a booking is cancelled this field will indicate the reason, if a booking is not cancelled this will be 0.
 

0 - Not cancelled
1 - Cancelled by customer request, see notes
2 - Cancelled by customer request, booked another tour
3 - Cancelled by staff, see notes
4 - Cancelled by staff, boook another tour
5 - Cancelled by staff, payment not received
6 - Cancelled by staff, tour not reached min. numbers
7 - Cancelled by staff, booking made in error
8 - Cancelled by staff, capacity exceeded
9 - Cancelled by staff, operational reasons
10 - Cancelled by staff, booking reopened for editing
11 - Cancelled by staff, bad weather
20 - Cancelled by system, expired quotation
21 - Cancelled by system, expired provisional booking

cancel_textTextual representation of the cancellation status.
E.g. "Not cancelled"
final_checkWill be 1 if the booking has had the "final check" completed by staff, 0 if it hasn't.
lead_customer_idID number for the lead customer
lead_customer_nameLead customer name
lead_customer_firstnameLead customer first name
lead_customer_surnameLead customer last name
customer_countNumber of customers on the booking
sale_currency3 digit sale currency, e.g. "USD"
sales_revenueAmount of revenue (in the sale_currency but excluding any currenct information)
sales_revenue_displayDisplay version of the revenue, includes currency symbol where applicable (e.g. US$100.00)
commissionAmount of commission
commission_taxAmount of commission tax
commission_currency3 digit commission currency, e.g. "USD"
commission_displayDisplay version of the commission, includes currency symbol where applicable (e.g. US$20.00)
commission_tax_displayDisplay version of the commission tax, includes currency symbol where applicable (e.g. US$2.50)
tracking_miscidA numeric value that can be set on the tracked links to divide up online tracking into sections (e.g. specific online marketing campaigns)
agent_refCould be a booking reference for the booking in the agent's own system. May be blank
agent_ref_componentsCould be a booking reference for the booking in the agent's own system, at a ticket level. May be blank
agent_typeThe type of agent, relates to who pays the balance, what that balance is and the status of bookings coming in
 
TRACK - No commission, customer pays balance
AFFILIATE - Commission, customer pays balance
RETAIL - Commission or net rates, agent pays balance
TRUSTED - Commission or net rates, agent pays balance, booking confirmed without payment
 
Will be blank if no agent
payment_statusNumeric representation of the booking payment status.
 
0 - No payment
1 - Deposit paid
2 - Deposit paid #2
3 - Full balance paid
4 - Refunded
payment_status_textTextual representation of the payment status.
E.g. "Full balance paid"
balance_owed_byEither C if the balance is owed by the customer (e.g. affiliate type booking), or A if the balance is owed by the Agent
balanceAmount remaining to be paid on the booking (in the sale_currency)
balance_displayDisplay version of the amount remaining to be paid on the booking, includes currency symbol where applicable (e.g. US$200.00)
balance_dueWhen the remaining balance is due. YYYY-MM-DD
Fields below are only returned to Tour Operators (not Partners)
agent_nameAgent name (if an agent is set on the booking)
agent_codeAgent code (if an agent is set on the booking)
agent_idTourCMS internal ID for agent (if an agent is set on the booking)

More information