Use Cases
Getting Started
General Overview and Format of Use Cases
This guide presents common use cases for interacting with the G Adventures reservation system through the WRITE methods of the API. Every client integration may vary with respect to the different functions that are implemented. This documentation enumerates these functions through use cases, in order of relevance. Each use case is structured withe the following sections:
Description
A brief description of the function, with links to the relevant resource documentation. The documentation for each resource should be consulted in full prior to implementation. Some details are given relating the use case to G Adventures products. In some cases, a specific resource is listed as a recommendation for testing.
References
Links to related use cases or documentation of request/response examples.
Preconditions
An enumerated list of relevant resource preconditions that must be met to implement this use case. It is recommended that these are used in client tests.
Postconditions
An enumerated list of relevant resource postconditions that will be present upon successful implementation of this use case. It is recommended that these are used in client tests.
Booking Life Cycle
Use cases are grouped in sections based on the life cycle of a booking. These sections are by no means mutually-exclusive. Integrations may mix and match use cases for the desired implementation that works best with the client systems.
Booking Tour Departures
In Booking Tour Departures we examine the core functionality for creating a booking. The use cases are ordered and represent the minimum implementation for any integration. This section should be the starting place for ANY integration. The general process for making a booking is:
Create a new booking
Think of this as an order number or shopping cart.
Create new customers
These are your clients who are making the booking.
Create a new departure service (a reservation on the departure)
Think of this as the main item in your shopping cart. A customer MUST be booked on a departure_service before any other actions can be performed on the booking. G Adventures does not allow booking add-ons such as accommodations, transports, activities, etc… without first booking a departure service.
Every new departure service is created with an Option status. When the departure service is on Option, the customer is temporarily reserving space on the departure but has not committed to the purchase. No payment is required to hold an Option. An Option can be held for a maximum of 4 days before it will automatically be Expired (reserved space released) by G Adventures.
Fulfill confirmation requirements
In order to Confirm a departure service, we need specific customer information. These confirmation requirements are enumerated in the departure, as each has different requirements.
This process of updating customer information can be eliminated by always providing these details (and hence meeting the requirements) when creating the customers. Why not always require the additional customer details in order to eliminate this extra step? Some implementations may want the ability to hold an Option with minimal set of information needed from the customer.
Confirm the departure service
Once the requirements are met, the departure service can be Confirmed. Think of this as the checkout step - the customer has confirmed that they wish to purchase the product.
Booking Tour Departures - Special Cases
Next, in Booking Tour Departures - Special Cases we enumerate very specific cases that some integrations may want to implement while others may not. Some of these use cases relate to special booking conditions such as:
Other use cases relate to departures that have special considerations and processes that must be followed.
Managing Bookings
Next, in Managing Bookings we explore use cases that often occur at a later date, after the initial booking is made:
Some of these use cases may be irrelevant if the integration is strict in requiring this detailed information from the customer at the time of booking. Some customers may not have the necessary information at the time of booking, so the ability to provide updates at a later date provides greater flexibility. These functions will map to backend processes in the client systems for each integration.
Booking Add Ons
Finally, in Booking Add Ons we identify use cases for booking add-ons to the core departure service. None of the add-ons can be booked as stand-alone products (i.e. always require a departure service on the booking before they can be booked).
In many implementations these functions will be used as part of the initial booking process, similar to adding items to a shopping cart. They are offered as stand-alone functions in order to facilitate the ability to book add-ons at a later date, after the initial booking is made with the core departure service item.
Confirming a Departure Service
Description
Confirming a departure service, for both a rooming and non-rooming departure.
Think of this as the checkout step - the customer has confirmed that they wish to purchase the product. This use case can be implemented as part of the initial booking process, or as a follow up process at a later date. Remember, an Option can be held for a maximum of 4 days before it will automatically be Expired (reserved space released) by G Adventures.
References
Preconditions
Postconditions
Booking Tour Departures - Special Cases
Booking with Existing Customers
Description
Create a booking for existing customers, with a departure service on a departure.
For repeat customers there is no need to create a new customer record when making a booking. If the customer ‘id’ is stored, this can be used for subsequent bookings at a later date. Using this methodology will ensure a complete view of a particular customer’s booking history, as well as save time inputting customer information that is stored in the G Adventures reservation system from the customer’s first booking.
References
Preconditions
Postconditions
Updating a Booking External ID Reference
Description
Update a booking ‘external_id’ field.
This field should be used to store the unique identifier for the corresponding object in the client’s backend system. The use of this field is encouraged, but optional. We do not enforce uniqueness of this field across records.
This field can also be set when a booking is created.
References
Preconditions
Postconditions
Expiring a Service
Description
Expiring a departure service, transport service, accommodation service, or activity service.
An Option can be held for a maximum of 4 days before it will automatically be Expired (reserved space released) by G Adventures. We encourage clients to follow up with their customers before this time and manually Expire any Option services that will not be Confirmed. There is never a cancellation fee service for expiring an Option.
References
Preconditions
Postconditions
the service ‘status’ is “Expired”
the service has an empty ‘status_transitions’ list
the service has an empty ‘customers’ list
the service has a ‘date_cancelled’ with the current date/time
the service has a ‘purchase_price’ of “0.00”
a new invoice is created and listed under the booking’s invoices sub-resource
Requesting Cancellation of a Service
Description
Submitting a request for the cancellation a departure service, transport service, accommodation service, or activity service.
G Adventures staff will be responsible for processing and confirming the cancellation, at which point the service ‘status’ will be changed to “Cancelled” and a fee service may be generated depending on the agency cancellation conditions. Once the service is Cancelled, a new invoice will be created and listed under the booking’s invoices sub-resource. Automatic notification of these changes can be accomplished using Webhooks. The postconditions once cancelled are the same as those for the Expiring a Service use case.
References
Preconditions
Postconditions
the service ‘status’ is “Request Cancellation”
the service has an empty ‘status_transitions’ list
no changes to the following service fields: ‘customers’, ‘date_cancelled’, ‘purchase_price’
Fulfilling CHECKIN Requirements
Description
Fulfilling departure/departure service CHECKIN requirements: ARRIVAL_FLIGHT_DETAILS, DEPARTURE_FLIGHT_DETAILS, INTERNATIONAL_TICKET_NUMBER, TRAVELLER_HEIGHT.
See Fulfilling CONFIRMATION Requirements for customer-related CHECKIN requirements: EMERGENCY_CONTACT_DETAILS, PASSPORT_ISSUE_DATE, PASSPORT_PLACE_OF_ISSUE, PLACE_OF_BIRTH.
There is currently no way to fulfill the following CHECKIN requirements via the API: PICKUP_POINT, APPLICATION_FORM_RECEIVED, COPY_OF_PASSPORT, CRIMINAL_BACKGROUND_CHECK_RECEIVED, LETTER_OF_INVITATION, LETTER_OF_REFERENCE_RECEIVED, PASSPORT_SIZED_PHOTO_RECEIVED. PICKUP_POINT relies on a new Location resource that will be released in the future. The other 7 CHECKIN requirements relies on the ability to POST/PUT documents, which will also be released in the future. The following CHECKIN requirements are fulfilled by G Adventures staff: COPY_OF_PASSPORT_SENT, COPY_OF_VISA_SENT, FIRST_NIGHT_HOTEL. The best way to know when these have been fulfilled is by monitoring the departure service resouce with Webhooks.
A departure service voucher will be generated by G Adventures staff once all CHECKIN requirements have been fulfilled. Again, the best way to know when these have been fulfilled is by monitoring the departure service resouce with Webhooks..
See the Booking Requirements section for details about each requirement and how it relates to departure service fields.
CHECKIN requirements must be met before the booking’s ‘date_of_first_travel’. We recommend obtaining these details from customers ASAP. Some implementations may want to request this information from the customer at time of booking so that the data can be used when creating the departure service as opposed to having to update it later. With that said, many customers do not have this information at the time of booking. As such, a process to update the information at a later date is usually needed.
Suggested testing tour dossiers: id 22429 (EWLA ‘product_line’) has ARRIVAL_FLIGHT_DETAILS, DEPARTURE_FLIGHT_DETAILS, and TRAVELLER_HEIGHT as CHECKIN requirements
Suggested testing tour dossiers: id 21838 (PHPT ‘product_line’) has INTERNATIONAL_TICKET_NUMBER as CHECKIN requirement
References
Preconditions
Postconditions
the departure service ‘incomplete_requirement’ item no longer appears in the list
the departure service list field associated with the particular requirement (‘arrival_flight_details’, ‘departure_flight_details’, ‘international_ticket_numbers’, or ‘traveller_heights’), has an item for each customer on the departure service, and all fields are not null for the item.
Booking Transports
Description
Add a Confirmed transport service to a booking with existing customers from a Confirmed departure service.
A transport service cannot be booked as a stand-alone product. A departure service must first be booked where the underlying departure ‘product’ contains the transport in the list of addons.
Usually a transport service is:
arrival transfer (from airport) before the start of a departure service, identified by the addons list item ‘finish_date’ matching the ‘start_date’ of the associated departure
departure transfer at the end (to airport) of a departure service, identified by the addons list item ‘start_date’ matching the ‘finish_date’ of the associated departure
There cannot be any gaps between the ‘finish_date’ of an arrival transport service and the ‘start_date’ of the associated departure service. Similarly, there cannot be any gaps between the ‘start_date’ of a post-night accommodation service and the ‘finish_date’ of the associated departure service. The exception to each of these rules occurs when either pre-night or post-night accommodation services are booked at the start or end of a departure service. In this case, there cannot be any gaps between the ‘finish_date’ of an arrival transport service and the ‘start_date’ of the earliest pre-night accommodation service. Similarly, there cannot be any gaps between the ‘start_date’ of a departure transport service and the ‘finish_date’ of the last accommodation service. In both cases, the accommodation services are those that are related to the same departure service for which the transport service is being added. The departure service has an underlying departure ‘product’. This departure contains all accommodations and transports in the addons list.
In most cases, the available transport addons will finish/start at the start/finish point of the departure. For arrival transfers, this can be verified by comparing the transport ‘finish_address’ to the ‘start_address’ of the departure. For departure transfers, this can be verified by comparing the transport ‘start_address’ to the ‘finish_address’ of the departure.
When adding a transport service to a Confirmed departure service, it will automatically be Confirmed. It is also possible to add an transport service to a departure service on Option, however the status of the new transport service will mirror that of the departure service (Option). The following fields are required to Confirm (automatically or manually) a transport service: ‘pickup_time’ & ‘flight_number’. An Option can be booked without these details, and then they can be added at Confirmation time.
Suggested testing tour dossier: DTWE Tour Dossier. Departures have arrival & departure transport addons.
References
Preconditions
Postconditions
Booking Activities
Description
Add a Confirmed activity service to a booking with existing customers from a Confirmed departure service.
An activity service is an optional activity that occurs during a departure service, but has an additional charge to participate. Some examples suggested for testing:
It cannot be booked as a stand-alone product. A departure service must first be booked where the underlying departure ‘product’ contains the activity in the list of addons.
When adding an activity service to a Confirmed departure service, it will automatically be Confirmed. It is also possible to add an activity service to a departure service on Option, however the status of the new activity service will mirror that of the departure service (Option). When the departure service is Confirmed, any associated activity services will also automatically be Confirmed.
References
Preconditions
Postconditions
Booking a Single Supplement
Description
Add a Confirmed single supplement service to a booking with existing customers from a Confirmed departure service.
A single supplement service is a booked single supplement, which is an optional surcharge that can be added for a customer who wishes to have their own room on the departure service. Pricing is always based on double-occupancy, so single travellers that do not purchase this option will share a room with another single traveller. For rooming trips, the single supplement is the surcharge to purchase the entire cabin. On most trips, a limited number of single supplements are available. They are usually booked by single customers.
Suggested testing tour dossiers (non-rooming): CRA Tour Dossier, a departure where “My Own Room” appears in addons
Suggested testing tour dossiers (rooming): XVCASX Tour Dossier, a departure where “My Own Room” appears in addons
A single supplement service cannot be booked as a stand-alone product. A departure service must first be booked where the underlying departure ‘product’ contains the single supplement in the list of addons.
When adding an single supplement service to a Confirmed departure service, it will automatically be Confirmed. It is also possible to add an single supplement service to a departure service on Option, however the status of the new single supplement service will mirror that of the departure service (Option). When the departure service is Confirmed, any associated single supplement services will also automatically be Confirmed.
References
Preconditions
Postconditions