Departure Services

A Departure Service is a booked instance of a departure product. If you are doing transactions via the G API, you’ll need to be creating departure services among other things.

We recommend reading Creating Your First Booking as it goes over the functions involved in building out a simple booking with services and customers. You can also read Machu Picchu Trips which covers how to book a Machu Picchu trip which can have multiple valid and overlapping itineraries.

References:

• Get a Departure Service

• Create a Departure Service

• Update a Departure Service

• Create a Departure Service with Room Code

XML Schema:

• commonTypes.xsd

• departure_services.xsd

Fields

Name	Type	Description
id (read-only)	String
href (read-only)	Field
name (read-only)	String	The name of this service.
status	String	The current status of the service: Option: The service is being held on option until the option_expiry_date. No deposit or payment is required to hold an option. An Option service can be Expired or Confirmed. On Request: The service has been requested by the client, but the request has not been sent to the local office. All departures with availability status REQUEST_SPACE can not be put on Option, but must be requested. Full payment is required. An On Request service can be Expired with no cancellation fees applied. Request Confirmation: The service has been requested by the client, and the request has been sent by G Adventures to the local office. A Request Confirmation service can be Cancelled with cancellation fees applied. Confirmed: The service is confirmed. Deposit is always required to confirm, and full payment will be required for a departure where FULL_PAYMENT_REQUIRED_TO_BOOK is present in the flags field. A Confirmed service can be Cancelled with cancellation fees applied. Waitlisted: The service is in a waitlist queue. A cancellation on the product will cause the service to automatically be moved to Option. Only product with availability status WAIT_LIST can be Waitlisted. A Waitlisted service can be Cancelled with no cancellation fees applied. Expired: The service is expired. An Option or On Request service is Expired at midnight EST when it reaches its option_expiry_date. A Waitlisted service can be Expired at any time, but will automatically be Expired when a departure reaches availability status REQUEST_SPACE. No cancellation fees will be applied. Request Cancellation: The service has been requested to be Cancelled. Cancellation fees will be applied when it is Cancelld by G Adventures staff (if applicable). Cancelled: The service is cancelled. A Request Confirmation or Confirmed service can be cancelled with cancellation fees applied. Active service status transitions: Option –> Confirmed/Expired On Request –> Request Confirmation/Expired Request Confirmation –> Request Cancellation Confirmed –> Request Cancellation Waitlisted –> Expired
status_transitions (read-only)	List	A list of status values to which this service can transition.
type (read-only)	String	The type of this resource.
sub_type (read-only)	String	A brief description of this service type.
start_date (read-only)	Date	The start date of this service.
finish_date (read-only)	Date	The finish date of this service.
customers	Field	The customers on this service.
id (read-only)	String
href (read-only)	Field
name	Nested Object
legal_first_name (required)	String	Legal first name as it appears on a passport.
legal_middle_name	String	Legal middle name as it appears on a passport.
legal_last_name (required)	String	Legal last name as it appears on a passport.
common_name	String	The name this person likes to be called if different from their legal name.
title (required)	String	The title. Valid values are: Mr, Mrs, Ms, and Miss
date_created (read-only)	Datetime	The date/time this service was created, in the standard Dates & Times.
date_confirmed (read-only)	Datetime	The date/time this service had its service status set to Confirmed, in the standard Dates & Times.
date_cancelled (read-only)	Datetime	The date/time this service had its service status set to Cancelled, in the standard Dates & Times.
option_expiry_date (read-only)	Datetime	The date/time when an Option service status will automatically be set to Expired, in the standard Dates & Times.
purchase_price (read-only)	Decimal	The currency-specific purchase price this service was Confirmed at, in the standard Currencies & Prices. The price reflected includes any promotions applied. The price is not locked until the service has its service status set to Confirmed (i.e. the price could change when the service status is on Option).
commission (read-only)	Decimal	The currency-specific commission amount that the booking agent will receive for this service, in the standard Currencies & Prices.
applied_promotion	Nested Object	The promotion applied to this service
id (read-only)	String
href (read-only)	Field
name	String	The name of the promotion used.
promotion_code	String	A unique code for this promotion.
discount_amount	Decimal	The currency-specific amount that has been discounted from the purchase_price. Add the discount_amount and purchase_price to see the original non-discounted price.
commission_rate	Integer	The commission rate for this promotion.
terms_and_conditions	String	The promotion applied to this service.
applied_promotions	Field	The promotions applied to this service
id (read-only)	String
href (read-only)	Field
name	String	The name of the promotion used.
promotion_code	String	A unique code for this promotion.
discount_amount	Decimal	The currency-specific amount that has been discounted from the purchase_price. Add the discount_amount and purchase_price to see the original non-discounted price.
commission_rate	Integer	The commission rate for this promotion.
terms_and_conditions	String	The promotion applied to this service.
flags (read-only)	List	A list of codes that, when present, require special considerations for a booked service. The list of departure service flags related to the current status of a request to hike the Inca Trail, or the option booked for services on these special departures: Service Status Flags SUSPENDED: This departure service has been suspended due to mitigating circumstances out of G Adventures’ control and will not be departing. Inca Trail Flags ON_INCA_TRAIL: Inca Trail permits have been obtained for all travellers on this service. REQUESTING_INCA_TRAIL: A request to hike the Inca Trail has been submitted. The permits have not yet been obtained for travellers on this service. ON_LARES_TREK: All travellers on this service will be hiking the Lares Trek as the Inca Trail is not available. CUZCO_STAY: All travellers on this service will stay in Cuzco, as either they have chosen this option or the Inca Trail permits are not available for this departure. INCA_TRAIL_UNKNOWN: A request to the local office has been made to confirm availability and additional local intricacies. This is an intermediary state which can occur before REQUESTING_INCA_TRAIL and any of the other states.
booking (read-only)	Reference Object
documents (read-only)	Field
id (read-only)	String
href (read-only)	Field
date_created (required)	Datetime	The time when the resource was created, in the standard Dates & Times.
type (read-only)	String	The document type, currently: INVOICE, ATOL_CERTIFICATE, VOUCHER.
audience (read-only)	String	The intended audience of this document. Either AGENT or CUSTOMER.
booking (read-only)	Reference Object	The related booking resource.
mime_type (read-only)	String	The Internet media type.
declined_reason (read-only)	Reference Object	The related declined reason resource.
product (read-only)	Reference Object
itinerary (read-only)	Nested Object	The itineraries for the departure of this service
id (read-only)	String
variation_id	String	The unique identifier of a specific variation of this itinerary
href (read-only)	Field
rooms	Field	A list of objects containing per customer rooming data for this service.
code (required)	String	A unique code for this room that is used when creating a booking. This code will never change and can be used as an identifier.
name	String	The name of this room.
customers	Field	A list of travellers that are booked on the service. Each service on a booking may have a different list of travellers. The list of travellers on a booking is the aggregate of the travellers on each service associated with the booking.
id (read-only)	String
href (read-only)	Field
name	Nested Object
legal_first_name (required)	String	Legal first name as it appears on a passport.
legal_middle_name	String	Legal middle name as it appears on a passport.
legal_last_name (required)	String	Legal last name as it appears on a passport.
common_name	String	The name this person likes to be called if different from their legal name.
title (required)	String	The title. Valid values are: Mr, Mrs, Ms, and Miss
deposit (read-only)	String	This is the entire deposit needed to confirm this service. The deposit can vary by each departure and is at times, dependent on the region of the customer.
extras_included (read-only)	Field	List of extras included with this service. Currently only includes’Complimentary Airport Lounge’ with associated customer IDs.
name (required)	String	The name of the extra included with this service.
customers (required)	List	The customers who are included in this extra.
incomplete_requirements (read-only)	Field	A list of requirements that are not yet met on this service. A list of requirements can be found here: Booking Requirements
type (required)	String	The requirement category. ‘CHECKIN’ means the requirement must be met before a voucher document resource can be generated for a booked service on this product. ‘CONFIRMATION’ means the requirement must be met in order to confirm a booked service.
name (required)	String	The name of this requirement.
code (required)	String	A unique code for this requirement. This code will never change and can be used as an identifier.
requirement_set (required)	String	A unique code for the set which contains this requirements. This code will never change and can be used as an identifier.
message (required)	String	A message describing that data needed to fulfill this requirement.
flags (required)	List	A brief description of this detail.
details (required)	Field	A list of informational details for this requirement. This is information that should be given to the customer when booking a service on this product.
summary (required)	String	A brief description of this detail.
description (required)	String	A full description of this detail.
detail_type (required)	Nested Object	A type of this detail.
code (required)	String	A unique code for this detail type. Possible values are: ‘CONFIRMATION_ONLY’, ‘ANY’. CONFIRMATION_ONLY means this detail is relevant for confirmations. ANY means this detail is relevant for any type of communication.
customer (required)	Nested Object
id (read-only)	String
href (read-only)	Field
name	Nested Object
legal_first_name (required)	String	Legal first name as it appears on a passport.
legal_middle_name	String	Legal middle name as it appears on a passport.
legal_last_name (required)	String	Legal last name as it appears on a passport.
common_name	String	The name this person likes to be called if different from their legal name.
title (required)	String	The title. Valid values are: Mr, Mrs, Ms, and Miss
arrival_flight_details (read-only)	Field	A list of arrival flight data objects for this service, per customer.
arrival_flight_number (required)	String	Arrival flight airline code and number, using the standard International Air Transport Association (IATA) airport codes.
arrival_flight_date_time (required)	Datetime	(‘Arrival flight datetime in the local timezone and in the standard Dates & Times.’,)
customer (required)	Nested Object
id (read-only)	String
href (read-only)	Field
name	Nested Object
legal_first_name (required)	String	Legal first name as it appears on a passport.
legal_middle_name	String	Legal middle name as it appears on a passport.
legal_last_name (required)	String	Legal last name as it appears on a passport.
common_name	String	The name this person likes to be called if different from their legal name.
title (required)	String	The title. Valid values are: Mr, Mrs, Ms, and Miss
departure_flight_details (read-only)	Field	A list of departure flight data objects for this service, per customer.
departure_flight_number (required)	String	Departure flight airline code and number, using the standard International Air Transport Association (IATA) airport codes.
departure_flight_date_time (required)	Datetime	(‘Departure flight datetime in the local timezone and in the standard Dates & Times.’,)
customer (required)	Nested Object
id (read-only)	String
href (read-only)	Field
name	Nested Object
legal_first_name (required)	String	Legal first name as it appears on a passport.
legal_middle_name	String	Legal middle name as it appears on a passport.
legal_last_name (required)	String	Legal last name as it appears on a passport.
common_name	String	The name this person likes to be called if different from their legal name.
title (required)	String	The title. Valid values are: Mr, Mrs, Ms, and Miss
international_ticket_numbers (read-only)	Field	A list of international ticket number objects for this service, per customer.
ticket_number (required)	String	13 digit ticket number
customer (required)	Nested Object
id (read-only)	String
href (read-only)	Field
name	Nested Object
legal_first_name (required)	String	Legal first name as it appears on a passport.
legal_middle_name	String	Legal middle name as it appears on a passport.
legal_last_name (required)	String	Legal last name as it appears on a passport.
common_name	String	The name this person likes to be called if different from their legal name.
title (required)	String	The title. Valid values are: Mr, Mrs, Ms, and Miss
traveller_heights	Field	A list of customer height data objects for this service.
height (required)	Integer	Height in centimeters (cm).
customer (required)	Nested Object
id (read-only)	String
href (read-only)	Field
name	Nested Object
legal_first_name (required)	String	Legal first name as it appears on a passport.
legal_middle_name	String	Legal middle name as it appears on a passport.
legal_last_name (required)	String	Legal last name as it appears on a passport.
common_name	String	The name this person likes to be called if different from their legal name.
title (required)	String	The title. Valid values are: Mr, Mrs, Ms, and Miss
components (read-only)	Field	Components for this departure service that detail the included accommodations, activities, and transports.
original_departure_service (read-only)	Reference Object	The original departure service for this service.
arriving_flights (read-only)	Field	The set of arriving flights associated with the departure service.
customer (read-only)	Reference Object
flights	Field	A list of objects containing per customer rooming data for this service.
departing_flights (read-only)	Field	The set of departing flights associated with the departure service.
customer (read-only)	Reference Object
flights	Field	A list of objects containing per customer rooming data for this service.
requirements (read-only)	Nested Object	A list of requirements associated with the departure service. This is similar to the set referenced on a booking, but scoped to the single service.

Get a Departure Service

GET /departure_services/(string: service_id)/

Create a Departure Service

POST /departure_services/

Example request:

POST /departure_services/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type:application/json

{
    "booking": { "id": "628209" },
    "product": { "id": "548112" },
    "customers": [
        { "id" : "1322952" }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": "1162093",
    "href": "/departure_services/1162093",
    "name": "Essential Vietnam and Cambodia",
    "status": "Option",
    "type": "departure_services",
    "sub_type": "Tour",
    "start_date": "2013-12-13",
    "finish_date": "2013-12-29",
    "customers": [
        {
            "id": "1322952",
            "href": "/customers/1322952",
            "name": {
                  "legal_first_name": "Hangouts",
                  "legal_last_name": "Overbets",
                  "legal_middle_name": null,
                  "common_name": null,
                  "title": "Mr"
            }
        }
    ],
    "date_created": "2013-08-28T16:10:31Z",
    "date_confirmed": null,
    "date_cancelled": null,
    "option_expiry_date": "2013-09-01T16:04:36Z",
    "purchase_price": "1899.00",
    "commission": "0.00",
    "applied_promotion": null,
    "applied_promotions": [],
    "flags": [],
    "booking": {
        "id": "628209",
        "href": "/bookings/628209"
    },
    "documents": null,
    "product": {
        "id": "548112",
        "href": "/departures/548112",
        "name": "Essential Vietnam and Cambodia"
    }
}

Create a Departure Service with Room Code

Every departure has an array of rooms, and for the majority of trips, the room is standard. For trips with multiple rooms, you must be explicit about the room code you wish to book, as each room will have different pricing.

POST /departure_services/

Example request:

POST /departure_services/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type:application/json

{
    "booking": { "id": "628209" },
    "product": { "id": "548112" },
    "rooms": {"code": "8 - 2"},
    "customers": [
        { "id" : "1322952" }
    ]
}

Update a Departure Service

Example request:

The request below expires an Optioned service and provides a reason.

PATCH /departure_services/1161864/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type: application/json

{
    "status": "Expired"
}