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 February
CLOSED_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.