TourCMS, a leading online booking and channel management solution is operated by Palisis.

Contact Info

Palisis AG
Florastrasse 18A
8610 Uster
support@palisis.com
+41 44 533 40 40

Learn More

Follow Us

home > support > API > Marketplace API > API: list bookings

List Bookings

Allows searching by several criteria, returns booking component details, payment details etc.

For more detail on a particular booking see Show booking.

An alternative, older endpoint Search Bookings remains available, however it is less performant and returns less detail.

REST info

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

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object list_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_id = 0;

// Optionally define search parameters
// Here we are searching for bookings made during a date range
$params = "made_date_start=2020-01-01&made_date_end=2020-04-30";

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

// 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

Not currently supported

VB examples use the .Net Client Library

Not currently supported

NodeJS examples use the NodeJS Wrapper

Not currently supported

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

Implementing yourself? Check the REST info for this endpoint.

Try it

Enter your TourCMS API credentials below to call the List Bookings endpoint.


            
            

        



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

		
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

		
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

		
cancel_date_start
cancel_date_end		Find bookings cancelled during a date range. YYYY-MM-DD

		
channel_id_booking_idLimit the results to a set list of bookings by passing in a list of IDs.


 
channel_id_booking_id=10_8 (Booking ID 8, from Channel ID 10 only)

channel_id_booking_id=10_8,10_100,10_101 (Booking IDs 8, 100, 101 only, from Channel ID 10 only)

		
per_pageNumber of bookings to return per page, default and maximum is 250

		
pagePage of results to return, default is 1 (the first page)

		
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

		
agent_refUse to search for bookings with a specific agent reference

		
booking_idLimit results to those matching Booking ID

		
piiOnly return bookings that match either lead customer email or surname

		
account_idLimit results to a particular TourCMS account

		
channel_idsLimit results to a comma separated list of channel ids

	




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)

		

			bookings
			
						
If any bookings are found, a bookings node will be returned containing:

							

							
									
XML NodeNotes

							
							
	

		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

							
voucher_urlIf the account is using the standard voucher system, this link will point to the page showing the voucher.
 
 

When the URL is visited the voucher will only be displayed if the booking is Confirmed status, if it is Quotation or Provisional status an alternative message will be displayed.

							
barcode_dataBarcode value used on TourCMS standard vouchers if a supplier has not provided their own subsytem reference.
 
Learn more about operator references, barcodes and vouchers in TourCMS

							
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

                            
lead_customer_countryLead customer country

                            
lead_customer_cityLead customer city

                            
lead_customer_postcodeLead customer postal code

                            
lead_customer_addressLead customer address

                            
lead_customer_emailLead customer email

                            
lead_customer_tel_homeLead customer home phone number

                            
lead_customer_tel_mobileLead customer mobile phone number

                            
lead_customer_contact_noteLead customer contact note

							
lead_customer_agent_refLead customer agent reference, could be a reference/ID for this particular customer in the agent's system

							
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)

							
agent_marketplace_idTourCMS marketplace ID for agent (if an agent is set on the booking)

							

			If Permission Level 3 or above ?
		


		
customer_special_requestText containing any special requests the customer has made

		
customers_agecat_breakdownE.g. "2 Adults"

			

				payments
				
							
If any payments have been made a payments node will be returned containing:

								

								
										
XML NodeNotes

								
								
		

			payment
			
						
There will be one payment node for each payment on the booking.

							
									
XML NodeNotes

							
							
								
payment_date_timeDate and Time for payment in the channel accounts local time. YYYY-MM-DD HH:MM:SS (24 Hr)

								
payment_valueValue of the payment, e.g. 100.00

								
payment_currencyCurrency of the payment, e.g. EUR

								
payment_value_displayDisplay version including currency symbol/code

								
payment_typeFree text
e.g. "Credit card"

								
gateway_modeThe gateway mode used, 'web', 'pos', 'moto'

								
payment_referenceFreetext reference number (possibly from the payment gateway)

								
payment_transaction_referenceReference number in a specific format (to enable us to refund a payment later, if a credit card payment) e.g. WORL|1224

								
payment_notePayment note

								
paid_byC if customer, A if agent

								
paid_by_idEither a customer or agent ID

							
							

							
				

			
	

	

			

			
			

				components
				
							
A components node containing:

								

								
										
XML NodeNotes

								
								
		

			component
			
						
There will be one component node for each component (tour/option/etc) on the booking.

							
									
XML NodeNotes

							
							
								
component_idInternal ID for the component

								
linked_component_idOptions are added to tours. If an option, this will be the ID of the tour component it is associated with

								
product_ide.g. tour_id if a tour

								
product_codee.g. the tour code if a tour

								
product_notee.g. pickup transfer zone (the note on a departure)

								
component_note

								
date_typedeparture, freesale, hotel, option, fee

								
date_ide.g departure id if a departure

								
date_codee.g. the departure code (if a departure)

								
start_dateYYYY-MM-DD format

								
end_dateYYYY-MM-DD format

								
start_timeHH:MM (24hr) (Tours only)

								
end_timeHH:MM (24hr) (Tours only)

								
start_time_utcsecondsTour start time in UTC seconds if a timezone and times are configured by the operator

								
end_time_utcsecondsTour end time in UTC seconds if a timezone and times are configured by the operator

								
component_namee.g. the tour name

								
local_paymentWhether the component is a local payment (i.e. due to be paid in destination rather than pre-paid) or not

								
customer_paymentFor agent bookings, indicates a component paid for by the customer rather than the agent

								
rate_descriptionRate note (freetext) (e.g. Adult)

								
rate_breakdownFor tours....
e.g r1|a means rate 1 / adult

														(s-senior, a-adult, y-youth, c-child, i-infant)

														(r1 is the rate_id from show tour)


								
For hotels....
Seniors|Adults|Children|Infants

								
supplier_noteSupplier note (can be used for holding date specific IDs from 3rd party reservation systems)

								
sale_quantityQuantity

								
sale_quantity_rulePERSON - sale_price is per person
GROUP - sale_price is per group

								
sale_tax_inclusive1 - tax inclusive, 0 tax added to sale price to create increased total

								
sale_tax_percentageTax percentage

								
sale_currencyCurrency the booking was actually taken in (e.g. "USD"). Duplicate of sale_currency, on booking, above, repeated for convenience

								
sale_priceSale price

								
tax_totalTax total, in sale_currency

								
sale_price_inc_tax_totalSale price including tax

								
sale_exchange_rateExchange rate FROM sale_currency to currency_base

								
currency_baseBase currency of the account (e.g. "GBP")

								
sale_price_basePrice, currency_base, that was sold in. CAN be per person or per GROUP (depending upon sale_quantity_rule)

								
tax_total_baseTax total, in currency_base

								
sale_price_inc_tax_total_baseTotal sale price (in currency_base) for this component, including tax

								
voucher_redemption_statusWhether this particular component has already been redeemed. "0" = Not redeemed yet, "1" = Already redeemed

								
bus_checkin_statusIf the tour operator (supplier) has bus checkins switched on this field will be returned and will indicate whether this particular component has already been checked in. "0" = Not checked in by the bus driver yet, "1" = Already checked in by the bus driver

								
voucher_redemption_usernameCheck in user

							
							

							
				

			
	

	

			

						
						

						
			

		




		




? Permission levels


Tour Operators will be able to view all data. The data visible to Marketplace Partners depends on the permission level granted on that particular channel (set by the channel operator when they connect). Marketplace Partners granted permission level 2 or above will be able to see most of the booking information plus basic customer details. Marketplace Partners granted permission level 3 will be able to see a bit more information on each customer including age/dob information plus a breakdown of payments made on the booking.



Remember, Marketplace Partners will only be able to see bookings that have their agent record set (i.e. either the booking or the customer came to the Operator via the Marketplace Partner).



More information