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

Search Bookings

PurposeGet a list of bookings.
NotesAllows searching by several criteria, returns just a basic overview of each booking.
REST info Call/p/bookings/search
/c/bookings/search
FormatsXML
Example/p/bookings/search.xml?page=2&per_page=20
VerbGET
Code

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)

Querystring parameters

Querystring parameters
ParameterNotes
made_date_startUse this parameter to specify the earliest booking date to search, if specified bookings made prior to this date will not be returned. YYYY-MM-DD
made_date_endUse this parameter to specify the latest booking date to search, if specified bookings made after to this date will not be returned. 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)
lead_customer_surnameLead customer surname (part matches also checked)
booking_nameBooking name (part matches also checked) (Often the main tour/hotel 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)
per_pageNumber of results to return per page. Max is 500.
pageInteger for which page number to return. Default is page 1

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 (Tour/Hotel) on a booking however may be renamed or reference a Tailor made itinerary
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.
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"
lead_customer_idID number for the lead customer
lead_customer_nameLead customer 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
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

© 2003-2012 Travel UCD Limited. All rights reserved. TourCMS® is a registered trademark of Travel UCD Limited, United Kingdom. View Privacy policy.

Free 1 hour webinar - An introduction to TourCMS, 31st May @ 3pm GMT / 4pm BST (UK). Check in your timezone and register »