home > support > API > Marketplace API > API: show booking

Show Booking

View booking information


Notes

Tour Operators can view all booking data, Marketplace Agents can view a subset of the datas allowed based on the permission level granted by the tour operator they are connecting with.

REST info

Endpoint/c/booking/show
FormatsXML
Example/c/booking/show.xml?booking_id=12345
VerbGET

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object show_booking ( int $booking, int $channel )


Parameters

$booking
ID for the booking we want to show
$channel
ID for the channel the booking is made with

Example

// Booking ID number
$booking = 12345

// ID for the channel (supplier) the booking was made with
$channel = 3;

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

// Get the booking node
$booking = $result->booking;

// Print the booking ID
print $booking->booking_id . "<br />";

// Print the Booking name
print $booking->booking_name . "<br />";

// Format and print the booking start and end dates
$start_date = strtotime($booking->start_date);
$start_date_display = date("jS F Y (l)", $start_date);
print "Start: ".$start_date_display. "<br />";

$end_date = strtotime($booking->end_date);
$end_date_display = date("jS F Y (l)", $end_date);
print "End: " . date("jS F Y (l)", $end_date) . "<br />";
12345
7 Day Hiking Tour
Start: 7th June 2011 (Tuesday)
End: 14th June 2011 (Tuesday)

C# examples use the .Net Client Library

Overload list

XmlDocument ShowBooking (int bookingId, int channelId)



Parameters

bookingId
Booking ID
channelId
ID for the channel that the booking belongs to

Example

// Reference System.Globalization for date formatting
using System.Globalization;


...


// Set the ID of the booking we want to view
int bookingId = 12345;

// Set the ID for the channel this booking is made with
int channelID = 3;

// Query the TourCMS API
XmlDocument doc = myTourCMS.ShowBooking(bookingId, channelId);

// Check the status
string status = doc.SelectSingleNode("//error").InnerText;

if(status == "OK")
{
 // Get the Booking ID
 string bkgId = doc.SelectSingleNode("//booking/booking_id").InnerText;
 Console.WriteLine(bkgId);

 // Get the Booking Name
 string bkgName = doc.SelectSingleNode("//booking/booking_name").InnerText;
 Console.WriteLine(bkgName);

 DateTime temp = new DateTime();

 // Get and format the Start date
 string bkgStart = doc.SelectSingleNode("//booking/start_date").InnerText;
 temp = DateTime.Parse(bkgStart);
 bkgStart = temp.ToString("D", CultureInfo.CreateSpecificCulture("en-US"));
 Console.WriteLine(bkgStart);

 // Get and format the End date
 string bkgEnd = doc.SelectSingleNode("//booking/end_date").InnerText;
 temp = DateTime.Parse(bkgEnd);
 bkgEnd = temp.ToString("D", CultureInfo.CreateSpecificCulture("en-US"));
 Console.WriteLine(bkgEnd);

} else {
 Console.WriteLine("Error: " + status);
}
12345
7 Day Hiking Tour
Tuesday, June 07, 2011
Tuesday, June 14, 2011

VB examples use the .Net Client Library

Overload list

XmlDocument ShowBooking (int bookingId, int channelId)



Parameters

bookingId
Booking ID
channelId
ID for the channel that the booking belongs to

Example

' Reference System.Globalization for date formatting
Imports System.Globalization


...


' Set the ID of the booking we want to view
Dim bookingId As Integer = 12345

' Set the ID for the channel this booking is made with
Dim channelID As Integer = 3

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

' Check the status
Dim status As String = doc.SelectSingleNode("//error").InnerText

If status = "OK" Then

 ' Get the Booking ID
 Dim bkgId As String = doc.SelectSingleNode("//booking/booking_id").InnerText
 Console.WriteLine(bkgId)

 ' Get the Booking Name
 Dim bkgName As String = doc.SelectSingleNode("//booking/booking_name").InnerText
 Console.WriteLine(bkgName)

 Dim temp As DateTime = new DateTime()

 ' Get and format the Start date
 Dim bkgStart As String = doc.SelectSingleNode("//booking/start_date").InnerText
 temp = DateTime.Parse(bkgStart)
 bkgStart = temp.ToString("D", CultureInfo.CreateSpecificCulture("en-US"))
 Console.WriteLine(bkgStart)

 ' Get and format the End date
 Dim bkgEnd As String = doc.SelectSingleNode("//booking/end_date").InnerText
 temp = DateTime.Parse(bkgEnd)
 bkgEnd = temp.ToString("D", CultureInfo.CreateSpecificCulture("en-US"))
 Console.WriteLine(bkgEnd)

Else If

 Console.WriteLine("Error: " & status)

End If
12345
7 Day Hiking Tour
Tuesday, June 07, 2011
Tuesday, June 14, 2011

NodeJS examples use the NodeJS Wrapper


Example

TourCMS.showBooking({
	bookingId: 8449,
	callback: function(response) {
	  console.log(response.booking.booking_name);
	}
});
7 Day Hiking Tour

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

Querystring parameters

Querystring parameters
XML NodeNotes
booking_id Internal ID number for a booking (perhaps retrieved via Search Bookings)

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
booking

The booking node contains the following child nodes.

XML NodeNotes
(Basic information)
booking_idBooking ID (Always present)
channel_idChannel ID
account_idAccount ID
channel_nameCompany brand name, e.g. "Example Tours"
made_date_timeDate and time the booking was made, in the local time of the channel account. Format is YYYY-MM-DD HH:MM:SS (24 hr)
start_dateDate the booking starts, generally based on the local time of the item being booked. Format is YYYY-MM-DD
end_dateDate the booking ends, generally based on the local time of the item being booked. Format is YYYY-MM-DD
booking_nameName for the booking (not the customer). Often this is the same as the main item being booked however it can be changed (for example on Tailor made / personalised bookings)
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
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_dataIf you are creating your own barcode on a voucher, please use this data (See notes about barcodes on the useful notes page)
(Customer information)
lead_customer_idID number for the lead customer
lead_customer_nameLead customer full name. Built from other name components
lead_customer_emailEmail address
lead_customer_tel_home Home number
lead_customer_tel_mobile Mobile number
lead_customer_contact_noteE.g. "Call after 7pm"
lead_customer_travelling1 if the lead customer is travelling on the booking, 0 if they aren't
customer_countNumber of customers on the booking. E.g. 2
customers

There will be a customers node containing...

XML NodeNotes
customer

... a customer node for each customer, contaiing:

XML NodeNotes
customer_idInternal ID
customer_nameE.g. "Mr Joe Bloggs"
titleTitle (e.g. Mr, Mrs, Miss etc)
firstnameFirstname
middlenameMiddle name
surnameSurname
If Permission Level 3 or above ?
customer_emailEmail address
customer_tel_home Home number
customer_tel_mobile Mobile number
customer_contact_noteE.g. "Call after 7pm"
gender"m" if male, "f" if female, blank if unknown
dobDate of birth YYYY-MM-DD
agecatAge category - 1 digit code (i-Infant, c-Child, a-Adult, s-Senior). Based on age at end of booking
insurance_numberTravel insurance number
insurance_supplier_nameTravel insurance supplier
insurance_noteTravel insurance note
If API called by Tour Operator ?
insurance_supplier_idInternal supplier ID number for the travel insurance
(Revenue and deposit information)
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)
depositDeposit amount for the booking, regardless of whether it has been paid e.g. 100
deposit_displayDisplay version of the deposit, includes currency symbol where applicable e.g. US$100.00
(Booking status information)
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
22 - Cancelled by customer (via website)
23 - Cancelled by agent (via website)

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.
expiry_dateThe date the quotation or provisional booking will expire (not show on confirmed or cancelled bookings)
booking_has_net_priceWhether the booking has Net rates
(Agent information)
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
(Payment summary)
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
components

A component represents a line item in a booking (e.g. a tour or option). Components will be listed in the display order that is as the booking tokens / user interface

XML NodeNotes
component

There will be a component node for each

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)
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)
component_namee.g. the tour name
product_type 1 - Accommodation (hotel/campsite/villa/ski chalet/lodge)
2 - Transport/Transfer
3 - Tour/cruise including overnight stay
4 - Day tour/trip/activity/attraction (No overnight stay)
5 - Tailor made
6 - Event
7 - Training/education
8 - Other
9 - Restaurant / Meal alternative
 

In the case of "2" (Transport/Transfer) there will be an attribute on the XML element indicating the direction of travel.
 
0 - Other / not set
1 - Airport to City
2 - City to Airport
3 - Two way return
 
E.g. for a return transfer <product_type direction="3">2<product_type>

Also there may be an airport code
E.g. for London Gatwick <product_type direction="3" airport_code="LGW">2<product_type>
sale_quantityQuantity
local_paymentWhether the component is a local payment (i.e. due to be paid in destination rather than pre-paid) or not
noteFor an airport transfer will contain terminal and flight info
supplier_noteSupplier note (can be used for holding date specific IDs from 3rd party reservation systems)
questions

If any questions were configured when this component was booked then a questions node will be returned containing:

XML NodeNotes
q

There will be an q node for each question, containing:

XML NodeNotes
question_keyIf answering using Update Booking Component this key will be used to identify which question is being answered.
questionThe primary question text to display to the customer, e.g. Please provide the approximate weights for each member of your party in kilograms (Kg)
explanationAdditional explanation text for the question, perhaps detailing why it is being requested or how it will be used
placeholderPlaceholder text, usually an example of the type of input required
question_internalA shortened label for the text, largely intended for staff use, e.g. Weight (kg)
repeatInteger. How many answers are expected. Some questions should be answered once per tour booking, others should be answered once per person, this field will display the correct number of answers expected, e.g. "2"
repeat_typeString. The value of the setting that drives the quantity, currently either 'Q' (if the question is set to be answered per person/quantity) or '1' (if the question is set to be answered once per tour booking)
answer_typeAn indication of the type of input expected, e.g. 'text', 'number', 'date' (and possibly more in future). Note that as far as the API goes this a suggestion only, TourCMS does not validate that the correct type of data is provided in an answer.
answer_mandatoryWhether the answer is mandatory (required). Note that as far as the API goes this is a suggestion only, TourCMS allows mandatory questions to be omitted or left unanswered
answers

An answers node containing:

XML NodeNotes
answer

An answer node for each answer to the question:

XML NodeNotes
answer_
value
The answer
guide_language

If guide languages have been loaded on this departure (if this node doesn't exist, none have been loaded, asssume all languages from the tour level are supported on this departure) a guide_language node will be returned containing the following:

XML NodeNotes
language Tour guide language, 2 digit, e.g. "fr".
redeemVoucher redemption instructions
receipt_infoAdditional text to be printed on receipts, perhaps indicating additions a base tour includes
pickup_nameHotel pickup name
pickup_timeHotel pickup time
pickup_noteHotel pickup note
pickup_descriptionHotel pickup description
pickup_route_codeHotel pickup route code
voucher_redemption_status Whether this particular component has already been redeemed. "0" = Not redeemed yet, "1" = Already redeemed
bus_checkin_status If 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
Price details
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
sale_tax_inclusive1 - tax inclusive, 0 tax added to sale price to create increased total
sale_quantity_rulePERSON - sale_price is per person
GROUP - sale_price is per group
sale_currencyCurrency the booking was actually taken in (e.g. "USD"). Duplicate of sale_currency, on booking, above, repeated for convenience
sale_pricePrice, in sale_currency, that was sold in. CAN be per person or per GROUP (depending upon sale_quantity_rule)
sale_tax_percentageTax percentage
tax_totalTax total, in sale_currency
sale_price_inc_tax_totalTotal sale price (in sale_currency) for this component, including tax
net_priceNet Price, in sale_currency, that was sold in. CAN be per person or per GROUP (depending upon net_price_quantity_rule)
net_price_quantity_rulePERSON - net_price is per person
GROUP - net_price is per group
net_price_tax_totalNet Tax total, in sale_currency
net_price_inc_tax_totalTotal Net price (in sale_currency) for this component, 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
If API called by Tour Operator (not Agent) ?
rate_code Additional field for cross sytem mapping
supplier_idSupplier ID
supplier_refSupplier reference
supplier_tour_codeSupplier tour code
supplier_nameSupplier name
operational_noteOperational note
cost_quantityQuantity (Normally the same as sale_quantity but you can get situations where the cost is say per vehicle, but the sale price is per person)
cost_tax_inclusive1 - tax inclusive, 0 tax added to cost price to create increased total
cost_quantity_rulePERSON - sale_price is per person
GROUP - sale_price is per group
cost_currencyCurrency of the cost. Can be different per component (i.e NOT set at booking level)
cost_pricePrice, in cost_currency. CAN be per person or per GROUP (depending upon cost_quantity_rule)
cost_tax_percentageTax percentage
cost_tax_totalTax total, in cost_currency
cost_price_inc_tax_totalTotal cost price (in cost_currency) for this component, including tax
cost_exchange_rateExchange rate FROM cost_currency to currency_base
cost_price_basePrice, currency_base. CAN be per person or per GROUP (depending upon cost_quantity_rule)
cost_tax_total_baseTax total, in currency_base
cost_price_inc_tax_total_baseTotal cost price (in currency_base) for this component, including tax
component_added_datetimeDate and time the component was added to the booking YYYY-MM-DD HH:MM:SS
upsell_usernameIf the booking was an upsell, the username of the staff member that carried out the upsell
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 there will be a payments node containing the following child nodes.

XML NodeNotes
payment

There will be a payment node for each

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
promo

If a promo code has been provided when starting the booking, a promo node will be returned containing:

XML NodeNotes
promo_code The promo code that was provided, e.g. "10PERCENT"
valid Whether the promotional code was valid or not. Will be "OK" if valid, otherwise will be "INVALID PROMO CODE"
value The value of the promotional code (e.g. "100")
value_type What the value is expressed as. Currently only "PERCENT" however in the future may be "FIXED_VALUE" to indicate a fixed amount in the sale currency.
customer_promo_membershp Membership number (if present)
If API called by Tour Operator (not Marketplace Partner) ?
important_noteThe staff entered "pinned note" on the booking
workflow_noteThe staff entered note form the "workflow" tab on the booking
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)
marketplace_agent_idTourCMS Marketplace agent ID. Consistent for the same travel agent, between TourCMS accounts. Can be zero, even when agent_id is set, if the booking is assigned to a travel agent but did not originate from the TourCMS Marketplace
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
agent_credentialsFurther information
custom_fields

If any custom fields are configured then a custom_fields node will be returned containing the following:.

XML NodeNotes
field

If any custom fields are configured then a custom_fields node will be returned containing the following:.

XML NodeNotes
nameCustom field name E.g. PickupPoint
valueValue for the custom field E.g. Hilton Hotel

? 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