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


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)


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