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:

  1. Create a new booking

Think of this as an order number or shopping cart.

  1. Create new customers

These are your clients who are making the booking.

  1. 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.

  1. 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.

  1. 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:

  • booking last minute, close to departure

  • booking departures that are full

  • booking many customers

  • etc…

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:

  • Cancelling/Expiring

  • Updating customer information

  • Fulfilling checkin requirements that must be met before the customer travels

  • etc…

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.

Booking Tour Departures

Holding an Option on a Non-Rooming Departure

Description

Create a booking and new customers, with an Option departure service on a non-rooming departure.

A non-rooming departure is one that is land-based (i.e. not on a ship).

All new departure services must initially be booked as an Option. They can then be Confirmed (see Confirming a Departure Service) once all CONFIRMATION requirements are fulfilled (see Fulfilling CONFIRMATION Requirements). 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.

Suggested testing tour dossiers: id 21783 (CRA ‘product_line’)

References

Preconditions

  • the departure does not have the “NO_OPTIONS” flag in the ‘flags’ list

  • the departure has only a single ‘rooms’ list item where ‘rooms.code’ is “STANDARD” (non-rooming)

  • the departure has ‘availability.status’ of “AVAILABLE”

  • the new customers must be within the ‘min_age’ and ‘max_age’ of one of the departure ‘price_bands’ for the ‘rooms’ item

  • there are less or equal new customers than the value of the departure ‘availability.status.total’

  • the number of new customers must be within the ‘min_travellers’ and ‘max_travellers’ of one of the departure ‘price_bands’ for the ‘rooms’ item

  • there are no ‘promotions’ listed on the departure

Postconditions

Holding an Option on a Rooming Departure

Description

Create a booking and new customers, with an Option departure service on a rooming departure.

A rooming departure is one that is based on travelling by ship (e.g. cruising, sailing, etc…). In most cases there are various cabin classes/options for different prices.

All new departure services must initally be booked as an Option. They can then be Confirmed (see Confirming a Departure Service) once all CONFIRMATION requirements are fulfilled (see Fulfilling CONFIRMATION Requirements). 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.

Suggested testing tour dossiers: id 21595 (XVCASX ‘product_line’)

References

Preconditions

  • same as Holding an Option on a Non-Rooming Departure

  • Exceptions:

    • the departure has one or more ‘rooms’ list items where ‘rooms.code’ is NOT “STANDARD”

  • Additions:

    • the departure ‘rooms’ list has an item with ‘availability.status’ of “AVAILABLE”

    • there are less or equal new customers than the value of the departure ‘rooms’ list ‘availability.status.total’

    • there are less or equal new customers than the value of the departure ‘rooms’ list ‘availability.status.total’

Postconditions

Fulfilling CONFIRMATION Requirements

Description

Fulfilling departure/departure service CONFIRMATION requirements related to customers: AGE_RESTRICTED, DATE_OF_BIRTH, NATIONALITY, PASSPORT_EXPIRY_DATE, PASSPORT_NUMBER.

A departure service can only be Confirmed (see Confirming a Departure Service) once all CONFIRMATION requirements are fulfilled.

See the Booking Requirements section for details on the relationship between each requirement and specific customer fields.

References

Preconditions

Postconditions

  • the departure service ‘incomplete_requirement’ item no longer appears in the list

  • the customer field(s) related to the specific requirement is/are NOT null and valid

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 a Departure with a Promotion

Description

Create a booking and new customers, with a departure service on a departure with a promotion.

Every agency has a promotions sub-resource for a complete list of current and past promotions. The same promotions are also attached to the individual departure resources.

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

Managing Bookings

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

  • the booking has an ‘external_id’ which matches the input value

Updating Transport Service Arrival Details

Description

Update a transport service ‘pickup_time’ and ‘flight_number’.

This information corresponds to the customer’s arrival/departure flight information. While it can be set when a transport service is created, in many cases a customer may book their flights at later date, at which point they will have the necessary information to update these details on the transport service.

References

Preconditions

Postconditions

  • the transport service has ‘pickup_time’ and ‘flight_number’ which match the input values

Confirming a Non-Departure Service

Description

Confirming a transport service, accommodation service, or activity service.

This use cases is similar to that of Confirming a Departure Service, except non-departure services currently do not have any CONFIRMATION requirements. Since non-departure services cannot be booked as stand-alone product, all necessary information for these add-ons is obtained via the departure service CONFIRMATION requirements.

When adding a transport service, accommodation service, or activity service to a Confirmed departure service, it will automatically be Confirmed. Manually confirming a non-departure service is only necessary if it is booked as an add-on to a departure service on Option.

References

Preconditions

Postconditions

  • the service ‘status’ is “Confirmed”

  • the service has a ‘date_confirmed’ with the current date/time

  • a new invoice is created and listed under the booking’s invoices sub-resource

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 Add Ons

Booking Accommodations

Description

Add a Confirmed accommodation service to a booking with existing customers from a Confirmed departure service.

An accommodation service cannot be booked as a stand-alone product. A departure service must first be booked where the underlying departure ‘product’ contains the accommodation in the list of addons.

Usually an accommodation service is:

  • pre-night(s) Hotel before the start of a departure service, identified by the addons list item ‘finish_date’ matching the ‘start_date’ of the associated departure

  • post-night(s) Hotel at the end 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 a pre-night accommodation 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.

In most cases, the available accommodation addons will be at the same Hotel as the start or end of a departure. This can be verified by comparing the accommodation ‘address’ to the ‘start_address’ or ‘finish_address’ of the departure.

When adding an accommodation service to a Confirmed departure service, it will automatically be Confirmed. It is also possible to add an accommodation service to a departure service on Option, however the status of the new accommodation service will mirror that of the departure service (Option).

Suggested testing tour dossier below contains departures which have pre & post accommodation addons:

References

Preconditions

Postconditions

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