home > support > API > managing dates & prices externally > show departure

Show departure

Show details of a specific tour departure, including bookings on that departure

Part of a series of API calls intended largely for managing dates and prices outside of TourCMS


Notes

Intended for internal use rather than displaying on a public / marketing website.
 
For Tour Operator usage only (not accessible by Marketplace Agents).

REST info

Endpoint/c/tour/datesprices/dep/manage/show
FormatsXML
Example/c/tour/datesprices/dep/manage/show?id=1&departure_id=3191
VerbGET

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object show_departure ( int $departure, int $tour, int $channel )


Parameters

$departure
ID for the departure to show
$tour
The Tour that the departure belongs to
$channel
The Channel that the tour belongs to

Example

// Set our Channel ID
$channel = 3930;

// Set the ID for the Tour that this departure belongs to
$tour_id = 1;

// Set the ID for the departure to show
$departure_id = 3191;

// Query the TourCMS API, getting the departure details
$result = $tourcms->show_departure($departure_id, $tour_id , $channel);

if($result->error == "OK") {
	echo "Spaces remaining: " . $result->tour->dates_and_prices->departure->spaces_remaining;
} else {
	echo $result->error;
}
Spaces remaining: 

C# examples use the .Net Client Library

Coming soon

VB examples use the .Net Client Library

Coming soon

NodeJS examples use the NodeJS Wrapper


Example

// Display spaces remaining on Departure ID 8117
TourCMS.showDeparture({
	channelId: 3930,
	tourId: 1,
	departureId: 8117,
	callback: function(response) {
	  if(response.error == "OK")
			console.log("Spaces remaining: " + response.tour.dates_and_prices.departure.spaces_remaining)
	}
});
Spaces remaining: 10

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

Querystring parameters

Querystring parameters
ParameterNotes
idTour ID
departure_idID of departure to show


The Channel ID is also passed via the request header.

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.
tour

A tour node containing the following:

XML NodeNotes
account_idAccount ID
channel_idChannel ID
tour_idTour ID
tour_nameTour name (this is backoffice tour name, not the channel specific distribution one)
tour_codeTour code
sale_currencyCurrency the customer prices are loaded in, e.g. "EUR".
 
Note this may be different to the currency customers actually book in which is configured at the Channel level (which may also apply a markup).
cost_currencyCurrency the supplier costs are loaded in, e.g. "USD"
quantity_rule1 - price x 1 (for group pricing)
Q - price x quantity (per person pricing)
max_booking_sizeMaximum quantity per booking
min_departure_sizeMinimum quantity required for the departure to go ahead
max_departure_sizeMaximum quantity bookable on the departure, across all bookings
dates_and_prices

A dates_and_prices node containing:

XML NodeNotes
departure

A departure node containing:

XML NodeNotes
departure_idThe ID of the departure requested
codeFreetext, optional code for the departure
start_dateDate the departure starts, YYYY-MM-DD
end_dateDate the departure ends, YYYY-MM-DD
start_timeHH:MM (24hr)
end_timeHH:MM (24hr)
noteNote, freetext
spaces_remainingSpaces remaining. Temporary bookings (that you cannot see) also reduce spaces remaining
supplier_noteSupplier note (can be used for holding date specific IDs from 3rd party reservation systems)
min_booking_sizeMinimum quantity allowed on a single booking
statusCurrent status of the departure:
 
OPEN - Open, bookable
CLOSED - Closed, not bookable
ASKFIRST - Ask first
 
Normally ask first status appears when very few spaces remain or when the it is a last minute booking. By default TourCMS will hide "ASKFIRST" dates from the Marketplace and only return those dates that are "OPEN", however some Tour Operators can choose to display "ASKFIRST" dates in their booking engine at which point they will also be distributed via the Marketplace.
auto_statusThe status TourCMS would automatically set this departure to, could be overridden by a member of staff closing the departure (see below). CLOSED, ASKFIRST, OPEN - Normally ask first status appears when very few spaces remain or when the it is a last minute booking.
manually_closedWhether the Departures has been manually closed or not.
 
1 = Yes, 0 = No
calc_quotationNumber of spaces that have been booked on "Quotation" status bookings
calc_provisionalNumber of spaces that have been booked on "Provisional" status bookings
calc_confirmedNumber of spaces that have been booked on "Confirmed" status bookings
spaces_blockedNumber of spaces blocked off by staff (e.g. spaces that can't be booked)
total_voucher_redeemNumber of spaces already where vouchers redeemed
total_bus_checkinNumber of spaces already where vouchers complete bus pickup redemption stage
special_offer

A special_offer node will always be returned regardless of whether there is a discount or not, it will contain:

XML NodeNotes
is_offer1 if there is a special offer, 0 if not
offer_priceThe price for the offer (if is_offer is 0 then this will be the same as the main departure price)
offer_price_displayDisplay version of the offer_price with currency information
offer_noteNote for the offer (free text)
rates

A rates node containing:

XML NodeNotes
rate

A rate node for each rate containing:

XML NodeNotes
rate_idE.g. "r1"
rate_nameE.g. "Adult"
customer_pricePrice
customer_price
_display
Price - display version (Includes HTML entity currency code and no decimals)
supplier_costCost
supplier_cost
_display
Cost - display version (Includes HTML entity currency code and no decimals)
agecat Age category (s-senior, a-adult, y-youth, c-child, i-infant)
agerange_min
agerange_max
Years. If blank, first check agecat, secondly assume is adult
rate_code Tour operators only. Additional field for cross sytem mapping
bookings

A bookings node containing:

XML NodeNotes
booking

A booking node for each booking on this departure, containing basic information about each booking:

XML NodeNotes
booking_idBooking ID
channel_idChannel ID
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"
lead_customer_idID number for the lead customer
lead_customer_nameFull 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_note
E.g. "Call after 7pm"
customer_special_
request
Freetext
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
has_local_paymentWhether the boking has "Local payment" items (i.e. payable in destination rather than pre-payable). Depending on the account settings, local payments may not be included in the overall booking total
agent_nameAgent name (if an agent is set on the booking)
agent_codeAgent code (if an agent is set on the booking)
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_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
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
component_nameE.g. the tour name
product_codee.g. the tour code if a tour
date_codeThe departure code
sale_quantityQuantity
product_notee.g. pickup transfer zone (the note on a departure)
noteNote added on to the component when booked, perhaps for a transfer this may be customer flight details
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 A language node for each tour guide language supported on this departure, 2 digit, e.g. "fr".
start_dateYYYY-MM-DD format
end_dateYYYY-MM-DD format
pickup_nameHotel pickup name
pickup_timeHotel pickup time
pickup_noteHotel pickup note
pickup_descriptionHotel pickup description
supplier_idSupplier ID
supplier_refSupplier reference
supplier_tour_codeSupplier tour code
supplier_nameSupplier name
operational_noteOperational note
voucher_redemption_status Whether this particular component has already been redeemed. "0" = Not redeemed yet, "1" = Already redeemed
redeem_voucher_key If the "voucher_redemption_status" for this component is "0", this field will be present and contain a key that can be passed to Redeem Voucher to redeem the voucher
redeem_voucher_key_reverse If the "voucher_redemption_status" for this component is "1" (i.e. the component has previously been redeemed) this field will be present and contain a key that can be passed to Redeem Voucher to reverse the redemption and set the voucher_redemption_status back to "0".
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
bus_checkin_key If the "bus_checkin_status" for this component is "0", this field will be present and contain a key that can be passed to Redeem Voucher to check the client in on the bus
bus_checkin_key_reverse If the "bus_checkin_status" for this component is "1" (i.e. the client has already been checked in by the bus driver) this field will be present and contain a key that can be passed to Redeem Voucher to reverse the checkin and set the bus_checkin_status back to "0".
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
rate_code Tour operators only. Additional field for cross sytem mapping
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")
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
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_base
Total sale price (in currency_base) for this component, including tax

More information