home > support > API > Marketplace API > managing dates & prices externally > update departure

Update departure

Create a new departure on a Tour

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


Notes

This API is for Tour Operator usage only (not accessible by Marketplace Agents).

Controlling available spaces

If you are building a user interface to control availability (e.g. perhaps to add or remove a bus on a particular trip), then you should be adjusting spaces_blocked in the table below. The default capacity / availability starting point will be max_departure_size on show departure.

If you know how many spaces remain, you may update spaces_available. E.g. if you know there are 7 spaces available, send us 7. However this is not advisable as when we update our system, we take into account temporary bookings, so if there happen to be 2 temporary bookings that do NOT convert to real bookings (i.e. the customer does not complete their booking process), at the point those temporary bookings are released, we will update to 9 spaces available.

Multi-lingual fields

Special offer notes (offer_note) AND product notes (note) can be multi-lingual. I.e. we can have a product note that has an English and a Spanish version, sharing the same field. In this situation we use a JSON to store the two (or more) values. The key to the JSON is a 2 letter language code (i.e. all English is en, not en-US for example)

These values are language specific, not channel specific


REST info

Endpoint/c/tour/datesprices/dep/manage/update
FormatsXML
Example/c/tour/datesprices/dep/manage/update.xml
 
POST data:
<?xml version="1.0"?>
<departure>
  <tour_id>1</tour_id>
  <departure_id>1</departure_id>
  <code>13:30-16:30</code>
</departure>
VerbPOST

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object update_departure ( SimpleXmlElement $departure_data , int $channel )


Parameters

$departure_data
SimpleXmlElement containing the departure information
$channel
The Channel that the tour belongs to

Example

// Set our Channel ID
$channel = 3930;

// Start building the departure XML
$departure = new SimpleXMLElement('<departure />');

// Set the Tour this departure should be added to
$departure->addChild('tour_id', 1);

// Set ID for the departure to update
$departure->addChild('departure_id', 3191);

// Add in the fields that need to be updated
// In this case just the code (times)
$departure->addChild('code', '13:30-16:30');

// Query the TourCMS API, updating the departure
$result = $tourcms->update_departure($departure , $channel);

if($result->error == "OK") {
	print "Departure updated";
} else {
	print $result->error;
}
Departure updated

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

TourCMS.updateDeparture({
  departure: {
    tour_id: 6,
    departure_id: 4954,
    special_offer: {
      offer_price: 45,
      offer_note: "Early booking discount"
    }
  },
  callback: function(response) {
    console.log(response.error);
  }
});
OK

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

Querystring parameters

There are no querystring parameters.

Post fields

The fields that can be used are as per the Create departure method, with the addition of a departure_id node to indicate which departure to update. At a bare minimum the tour_id and departure_id must be provided.

Post fields
XML NodeNotes
departure

A departure containing:

XML NodeNotes
tour_idThe Tour that the departure belongs to.
departure_idThe Departure to update.
codeDeparture code. May be in format 09:00-17:00 for day tours with specific time, if so the start_time and end_time fields may be populated. For start_time and end_time to be populated the tour will need to have the Multiple start & end times option selected in the Times & Cutoffs tab of Tour CMS
start_dateStart date (YYYY-MM-DD)
end_dateEnd date (YYYY-MM-DD)
noteNote for the departure (free text)
supplier_noteSupplier note (can be used for holding date specific IDs from 3rd party reservation systems)
guide_language

If you would like to specify which guide languages are available, list them here:

XML NodeNotes
language Tour guide language, 2 digit, e.g. "fr".
manually_closedSet to 1 to manually close the departure, 0 (or leave) to not
spaces_blockedNumber of spaces to block off sale (e.g. spaces that can't be booked). Can be negative to ADD capacity to a specific departure

See notes at bottom of page
spaces_availableUpdate the number of spaces that are available. Setting this value will calculate a spaces_blocked value that will make the tour capacity remaining equal to the supplied spaces_available value. NOT be used in conjunction with spaces_blocked

See notes at bottom of page
special_offer

To provide a discounted price for the first rate add a special offer node containing:

XML NodeNotes
offer_priceThe price for the offer. The currency should be in the base currency for the account.
offer_noteNote for the offer (free text)
rates

A rates node containing:

XML NodeNotes
rate

A rate node for each rate including:

XML NodeNotes
rate_idThe identifier for the rate. A list of Rate IDs for a particular Tour can be found via the Tour Show method
customer_priceThe customer price for the rate. In the base currency for the account
supplier_costThe supplier cost for the rate. In the cost currency set on the Tour.

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
departure_idDeparture ID

More information