Machu Picchu Trips¶
Note
JSON examples will not include everything, they have been shortened to include only the details needed for the explanation.
You can read Using Itineraries For A Tour for more information on showing multiple itinerary options.
In tour_dossiers¶
G Adventure’s tours will typically have one itinerary that is valid for
a date range. This can be determined with the
tour_dossiers.structured_itineraries[]
list, iterating over the
objects and finding the object that has an entry in the
valid_during_ranges[]
list where the end_date
value is null
OR a
date that is still in the future. There are some scenarios where
more than one itinerary will be valid for a tour:
The existing itinerary has been given an end-date that is in the future AND there is an itinerary that has a start-date after the existing itinerary’s end-date.
Machu Picchu trips - which will have 2 or more active variations.
For Machu Picchu trips, we will typically have three variations. These variations are:
Inca Trail
Lares Trek
Machu Picchu by Train (formerly Cusco Stay)
We’ll be using Tour Dossier 22983 (SPIT) The Inca Trail as an example.
SPIT structured_itineraries
"structured_itineraries": [ { "id": "1663", "variation_id": "5437", "href": "https://developers.gadventures.com/playground/itineraries/1663/5437", "valid_during_ranges": [ { "start_date": "2018-01-01", "end_date": null } ] }, { "id": "1426", "variation_id": "5441", "href": "https://developers.gadventures.com/playground/itineraries/1426/5441", "valid_during_ranges": [ { "start_date": "2018-01-01", "end_date": null } ] }, { "id": "1664", "variation_id": "10508", "href": "https://developers.gadventures.com/playground/itineraries/1664/10508", "valid_during_ranges": [ { "start_date": "2025-08-01", "end_date": null } ] } ],
This tour has 3 valid itineraries, which have a null
end_date value:
https://developers.gadventures.com/playground/itineraries/1663/5437
name: Inca Trail
flags: [ON_INCA_TRAIL]
https://developers.gadventures.com/playground/itineraries/1426/5441
name: Lares Trek
flags: [ON_LARES_TREK]
https://developers.gadventures.com/playground/itineraries/1664/10508
name: Machu Picchu by Train from August 1, 2025 onwards
flags: [CUZCO_STAY]
We can retrieve each of the itineraries to get their name
(included
above for convenience), along with their flags
value. These are
important for how Machu Picchu trip variations are booked.
In departures¶
Now that we have our itinerary variations - how can we join them to the
departures
instances? The departures
resource also contains a
structured_itineraries[]
list field. This will tell you what
itineraries are valid for a particular departure. We’ll look at an
example for SPIT:
Departure 1317452 structured_itineraries
"structured_itineraries": [ { "id": "1663", "variation_id": "5437", "href": "https://developers.gadventures.com/playground/itineraries/1663/5437", "valid_during_ranges": [ { "start_date": "2018-01-01", "end_date": null } ] }, { "id": "1426", "variation_id": "5441", "href": "https://developers.gadventures.com/playground/itineraries/1426/5441", "valid_during_ranges": [ { "start_date": "2018-01-01", "end_date": null } ] }, { "id": "1664", "variation_id": "10508", "href": "https://developers.gadventures.com/playground/itineraries/1664/10508", "valid_during_ranges": [ { "start_date": "2025-08-01", "end_date": null } ] } ],
We can use the departures.structured_itineraries[]
list to determine
the itineraries that are valid and display that information for the
departures as you list them.
Booking Machu Picchu trips¶
The below sequence diagram outlines the process for booking a Machu Picchu trip.

Refer to the Creating Your First Booking and Confirming Services tutorials for the full process of making and confirming a booking.
Note
Booking Machu Picchu trips has an additional set of requirements
that must be fulfilled in order to transition the departure service to a
"Confirmed"
status. Those requirements can be found on the
departures.requirements[]
list field, and will be denoted with
type: CONFIRMATION
.
In most cases for Machu Picchu trips, the CONFIRMATION requirements will be the “Passport Number” and “Passport Expiry Date”.
"requirements": [
{
"type": "CONFIRMATION",
"name": "Passport Expiry Date",
"code": "PASSPORT_EXPIRY_DATE",
"message": "Passport expiry date must be submitted for this product. The 'expiry_date' field (in the 'passport' data) must be set in the customer resource.",
"flags": [],
"details": []
},
{
"type": "CONFIRMATION",
"name": "Passport Number",
"code": "PASSPORT_NUMBER",
"message": "Passport number must be submitted for this product. The 'number' field (in the 'passport' data) must be set in the customer resource.",
"flags": [],
"details": []
},
]
These requirements can be fulfilled by creating or updating the Customers resource with the following values in the payload.
New customer¶
POST /customers
to include passport information
{
"account_email": "email@example.com",
"date_of_birth": "1990-01-01",
"name": {
"legal_first_name": "FirstName",
"legal_last_name":" LastName",
"title": "Mr"
},
"nationality": {
"id": "40"
},
"passport": {
"number": "12345678",
"expiry_date": "2030-01-01"
}
}
Existing customer¶
PATCH /customers/{id}
to update passport information
{
"passport": {
"number": "12345678",
"expiry_date": "2030-01-01"
}
}
Book “Inca Trail” variation¶
When booking a Machu Picchu trip and using the standard payload for the
POST /departure_services
request, this will result in our system
attempting to book the “Inca Trail” variation of the trip. The flags
value should NOT be provided in the payload.
{
"booking": {
"id": "1234567"
},
"customers": [
{
"id": "2345678"
}
],
"product": {
"id": "1317452"
},
"rooms": {
"code": "STANDARD"
}
}
Let’s note some caveats with this process.
If the departures.flags[]
field contains any of the following
values:
INCA_CLOSURE
- typically for departures in FebruaryCLOSED_INCA_TRAIL__SO
- indicates Inca Trail permits are sold-out for this departure.CLOSED_INCA_TRAIL__OR
- indicates Inca Trail permits are on-request for this departure
It means that you can still create the service as above, but the resulting
departure_services
resource will come back with a flags
value of
INCA_TRAIL_UNKNOWN
.
To book a Machu Picchu trip using one of the variations, you can include an
additional flags
field in the payload when creating a departure_services
resource. POST /departure_services
Note
This is entirely dependant on which itineraries are available for the departure.
For Lares Trek variation¶
We would use the ON_LARES_TREK
flag, which is seen on the
itineraries.flags[]
field for the Lares Trek variation
{
"booking": {
"id": "1234567"
},
"customers": [
{
"id": "2345678"
}
],
"product": {
"id": "1317452"
},
"rooms": {
"code": "STANDARD"
},
"flags": ["ON_LARES_TREK"]
}
For Machu Picchu by Train¶
We would use the CUZCO_STAY
flag, which is seen on the
itineraries.flags[]
field for the Machu Picchu by Train
variation
Note
The name of this variation will be “Machu Picchu by Train”, this
is a recent name change. It was previously called “Cusco Stay”.
The underlying flags
value has not changed which is why we still
use it when attempting to book this variation
{
"booking": {
"id": "1234567"
},
"customers": [
{
"id": "2345678"
}
],
"product": {
"id": "1317452"
},
"rooms": {
"code": "STANDARD"
},
"flags": ["CUZCO_STAY"]
}
Updating INCA_TRAIL_UNKNOWN to one of the variations¶
If a departure_services
resource was created and comes back with
INCA_TRAIL_UNKNOWN
, it is possible to update that service to one of
the two variations, provided they exist for the departure. This can be
done with a PATCH /departure_services/{id}
request with the
following payload:
Lares Trek¶
{
"flags": ["ON_LARES_TREK"]
}
Machu Picchu by Train¶
{
"flags": ["CUZCO_STAY"]
}
CLOSED_INCA_TRAIL__OR - requesting Inca Trail¶
If a departure has the CLOSED_INCA_TRAIL__OR
flag and you want to
book the Inca Trail
variation. When the departure_services
resource status is updated to "Confirmed"
, our reservation system
will trigger an additional status update to attempt to request an
Inca Trail permit. This state is reflected with the
departure_services.flags[]
value of "REQUESTING_INCA_TRAIL"
.
Note
This still does not mean that booking the Inca Trail will be guaranteed, and there may likely need to be a manual follow up with the Agency or Passenger when this becomes the case.