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
Formats	XML
Example	/c/tour/datesprices/dep/manage/show?id=1&departure_id=3191
Verb	GET

Code samples

PHP
C#
VB
NodeJS
Other

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
Parameter	Notes
id	Tour ID
departure_id	ID of departure to show

The Channel ID is also passed via the request header.

Response fields

XML Node

Notes

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 Node

Notes

account_id

Account ID

channel_id

Channel ID

tour_id

Tour ID

tour_name

Tour name (this is backoffice tour name, not the channel specific distribution one)

tour_code

Tour code

sale_currency

Currency 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_currency

Currency the supplier costs are loaded in, e.g. "USD"

quantity_rule

1 - price x 1 (for group pricing)
Q - price x quantity (per person pricing)

max_booking_size

Maximum quantity per booking

min_departure_size

Minimum quantity required for the departure to go ahead

max_departure_size

Maximum quantity bookable on the departure, across all bookings

dates_and_prices

A dates_and_prices node containing:

XML Node

Notes

departure

A departure node containing:

XML Node

Notes

departure_id

The ID of the departure requested

code

Freetext, optional code for the departure

start_date

Date the departure starts, YYYY-MM-DD

end_date

Date the departure ends, YYYY-MM-DD

start_time

HH:MM (24hr)

end_time

HH:MM (24hr)

note

Note, freetext

spaces_remaining

Spaces remaining. Temporary bookings (that you cannot see) also reduce spaces remaining

supplier_note

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

min_booking_size

Minimum quantity allowed on a single booking

status

Current 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_status

The 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_closed

Whether the Departures has been manually closed or not.

1 = Yes, 0 = No

calc_quotation

Number of spaces that have been booked on "Quotation" status bookings

calc_provisional

Number of spaces that have been booked on "Provisional" status bookings

calc_confirmed

Number of spaces that have been booked on "Confirmed" status bookings

spaces_blocked

Number of spaces blocked off by staff (e.g. spaces that can't be booked)

total_voucher_redeem

Number of spaces already where vouchers redeemed

total_bus_checkin

Number of spaces already where vouchers complete bus pickup redemption stage

fixed_sale_price

For accounts with “Fixed sale price” functionality enabled, indicates whether this particular departure has been flagged as having a fixed sale price (overriding cost+ margin logic)

1 = fixed sale price, 0 = regular price

special_offer

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

XML Node	Notes
is_offer	1 if there is a special offer, 0 if not
offer_price	The price for the offer (if is_offer is 0 then this will be the same as the main departure price)
offer_price_display	Display version of the offer_price with currency information
offer_note	Note for the offer (free text)

rates

A rates node containing:

XML Node

Notes

rate

A rate node for each rate containing:

XML Node	Notes
rate_id	E.g. "r1"
rate_name	E.g. "Adult"
customer_price	Price
customer_price _display	Price - display version (Includes HTML entity currency code and no decimals)
supplier_cost	Cost
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 Node

Notes

booking

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

XML Node

Notes

booking_id

Booking ID

channel_id

Channel ID

status

Status 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_text

Textual representation of the booking status.
E.g. "Confirmed (A)"

cancel_reason

If 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_text

Textual representation of the cancellation status.
E.g. "Not cancelled"

lead_customer_id

ID number for the lead customer

lead_customer_name

Full name. Built from other name components

lead_customer_email

Email 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_status

Numeric representation of the booking payment status.

0 - No payment
1 - Deposit paid
2 - Deposit paid #2
3 - Full balance paid
4 - Refunded

payment_status_
text

Textual representation of the payment status.
E.g. "Full balance paid"

balance_owed_by

Either C if the balance is owed by the customer (e.g. affiliate type booking), or A if the balance is owed by the Agent

balance

Amount remaining to be paid on the booking (in the sale_currency)

balance_display

Display version of the amount remaining to be paid on the booking, includes currency symbol where applicable (e.g. US$200.00)

balance_due

When the remaining balance is due. YYYY-MM-DD

has_local_payment

Whether 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_name

Agent name (if an agent is set on the booking)

agent_code

Agent code (if an agent is set on the booking)

agent_ref

Could be a booking reference for the booking in the agent's own system. May be blank

agent_ref_
components

Could be a booking reference for the booking in the agent's own system, at a ticket level. May be blank

agent_id

TourCMS internal ID for agent (if an agent is set on the booking)

marketplace_
agent_id

TourCMS 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_type

The 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 Node

Notes

component

There will be a component node for each

XML Node

Notes

component_id

Internal ID for the component

component_name

E.g. the tour name

product_code

e.g. the tour code if a tour

date_code

The departure code

sale_quantity

Quantity

product_note

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

note

Note 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 Node	Notes
language	A language node for each tour guide language supported on this departure, 2 digit, e.g. "fr".

start_date

YYYY-MM-DD format

end_date

YYYY-MM-DD format

pickup_name

Hotel pickup name

pickup_time

Hotel pickup time

pickup_note

Hotel pickup note

pickup_description

Hotel pickup description

supplier_id

Supplier ID

supplier_ref

Supplier reference

supplier_tour_code

Supplier tour code

supplier_name

Supplier name

operational_note

Operational 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_description

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

rate_breakdown

For 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_inclusive

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

sale_quantity_rule

PERSON - sale_price is per person
GROUP - sale_price is per group

sale_currency

Currency the booking was actually taken in (e.g. "USD")

sale_price

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

sale_tax_percentage

Tax percentage

tax_total

Tax total, in sale_currency

sale_price_
inc_tax_total

Total sale price (in sale_currency) for this component, including tax

sale_exchange_rate

Exchange rate FROM sale_currency to currency_base

currency_base

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

sale_price_base

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

tax_total_base

Tax total, in currency_base

sale_price_inc
_tax_total_base

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

questions

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

XML Node

Notes

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

XML Node

Notes

question_key

If answering using Update Booking Component this key will be used to identify which question is being answered.

question

The primary question text to display to the customer, e.g. Please provide the approximate weights for each member of your party in kilograms (Kg)

explanation

Additional explanation text for the question, perhaps detailing why it is being requested or how it will be used

placeholder

Placeholder text, usually an example of the type of input required

question_internal

A shortened label for the text, largely intended for staff use, e.g. Weight (kg)

repeat

Integer. 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_type

String. 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_type

An 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_mandatory

Whether 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 Node

Notes

answer

An answer node for each answer to the question:

XML Node	Notes
answer_ value	The answer

Contact Info

Learn More

Follow Us

Show departure

Notes

REST info

Code samples

Description

Parameters

Example

Example

Querystring parameters

Response fields

More information