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.
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:
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.
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.
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
a new booking is created
the new booking ‘currency’ is set to ‘currency’ value that was POSTed
the new booking ‘date_of_first_travel’ matches the departure ‘start_date’
the new booking ‘date_of_last_travel’ matches the departure ‘finish_date’
the new customers are created with all input parameters persisting in the object representation
a new departure service is created and listed under the booking’s services sub-resource
the new departure service ‘customers’ list contains all new customers
the new departure service has ‘status’ “Option”
the new departure service has ‘status_transitions’ [“Confirmed”, “Expired”]
the new departure service has an ‘option_expiry_date’ 4 days in the future
the new departure service ‘purchase_price’ matches the currency-specific price listed in the departure (as per preconditions), multiplied by the number of customers
the departure service has a null ‘applied_promotion’ (see also Booking a Departure with a Promotion)
the new departure service ‘product’ is linked to the departure
a new invoice is created and listed under the booking’s invoices sub-resource
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
- 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
- Additions:
each item in the new departure service ‘rooms’ list, has a value in the ‘code’ field that matches the departure (linked via the departure service ‘product’) rooms list item used to create the departure service
each new customer appears in one of the departure service ‘rooms’ list items
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
see similar: Fulfilling CHECKIN Requirements
Preconditions
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
a departure service with an ‘incomplete_requirement’ item of ‘type’ “CONFIRMATION” and ‘code’ equal to that of the specific requirement
the customer field(s) related to the specific requirement is/are null or invalid
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
see first Fulfilling CONFIRMATION Requirements
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
the departure service ‘status’ is “Option”
the departure service has “Confirmed” in the ‘status_transitions’
the departure service has no ‘incomplete_requirements’ list items with ‘type’ “CONFIRMATION”
Postconditions
the departure service has ‘status’ “Confirmed”
the departure service has ‘status_transitions’ [“Request Cancellation”]
the departure service has an ‘date_confirmed’ with the current date/time
the departure service has a null ‘option_expiry_date’
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
same as Holding an Option on a Non-Rooming Departure or Holding an Option on a Rooming Departure
- Exceptions:
there are ‘promotions’ listed on the departure (can be found easily by looking at the agency.promotions sub-resource)
Postconditions
same as Holding an Option on a Non-Rooming Departure or Holding an Option on a Rooming Departure
- Exceptions:
the new departure service has a non-null ‘applied_promotion’ with ‘id’, ‘name’, ‘promotion_code’, and ‘terms_and_conditions’ values equal to the promotion resource linked in the departure ‘rooms[].price_bands[].prices[].promotions’ list item
the new departure service ‘applied_promotion.discount_amount’ value (multiplied by the number of customers) equals the departure ‘rooms[].price_bands[].prices[].promotions[].amount’ value for the currency that matches the booking ‘currency’
the new departure service ‘purchase_price’ is equal to the currency-specific price listed in the departure (as per preconditions), multiplied by the number of customers, minus the departure service ‘applied_promotion.discount_amount’
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
same as Holding an Option on a Non-Rooming Departure or Holding an Option on a Rooming Departure
- Exceptions:
the existing 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 existing customers than the value of the departure ‘availability.status.total’
the number of existing customers must be within the ‘min_travellers’ and ‘max_travellers’ of one of the departure ‘price_bands’ for the ‘rooms’ item
Postconditions
same as Holding an Option on a Non-Rooming Departure or Holding an Option on a Rooming Departure
- Exceptions:
no new customers are created
the new departure service ‘customers’ list contains all existing customers
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
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
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
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
see first Booking Transports
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
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
see also: Confirming a Departure Service
Preconditions
the service’s booking has a ‘date_of_first_travel’ that is in the future
the service ‘status’ is “Option”
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
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
see first: Confirming a Departure Service
the service’s booking has a ‘date_of_first_travel’ that is in the future
the service ‘status’ is “Option” or “On Request” or “Waitlisted
the departure service has “Expired” in the ‘status_transitions’
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
same as Expiring a Service
Preconditions
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
see first: Confirming a Departure Service
the service’s booking has a ‘date_of_first_travel’ that is in the future
the service ‘status’ is “Confirmed” or “Request Confirmation”
the departure service has “Request Cancellation” in the ‘status_transitions’
Postconditions
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
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
see first: Confirming a Departure Service
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
a departure service with an ‘incomplete_requirement’ item of ‘type’ “CHECKIN” and ‘code’ equal to that of the specific requirement
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 departurepost-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
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
see first: Confirming a Departure Service
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
a departure service with ‘status’ “Confirmed”
the departure service ‘product’, is a departure with an
addons
item of type “accommodations”the departure service ‘product’, is a departure with ‘availability.status’ not equal to “REQUEST_SPACE”
the accommodation ‘rooms’ list has an item with ‘availability.status’ of “AVAILABLE”
the number of departure service existing customers is less than or equal to the value of the accommodation ‘rooms’ list item ‘availability.status.total’
the number of nights being booked, must be between the ‘min_nights’ and ‘max_nights’ of the accommodation ‘rooms’ list item
the ‘start_date’ and ‘finish_date’ being booked must be within the ‘start_date’ and ‘finish_date’ of one of the accommodation ‘season_dates’ for the ‘rooms’ list item
the ‘start_date’ and ‘finish_date’ being booked can not be within the ‘start_date’ and ‘finish_date’ of one of the accommodation ‘blackout_dates’ for the ‘rooms’ list item
the number of departure service existing customers must be within the ‘min_travellers’ and ‘max_travellers’ of one of the accommodation ‘price_bands’ for the ‘rooms’ list item
the existing departure service’s customers must be within the ‘min_age’ (if not null) and ‘max_age’ (if not null) of one of the accommodation ‘price_bands’ for the ‘rooms’ list item
Postconditions
a new accommodation service is created and listed under the booking services sub-resource
the new accommodation service has ‘status’ “Confirmed”
the new accommodation service has ‘status_transitions’ [“Request Cancellation”]
the new accommodation service has ‘start_date’ and ‘finish_date’ matching the input values
the new accommodation service ‘customers’ list is the same as the departure service
the new accommodation service has an ‘date_confirmed’ with the current date/time
the new accommodation service has a null ‘option_expiry_date’
the new accommodation service ‘purchase_price’ matches the currency-specific price listed in the accommodation (as per preconditions), multiplied by the number of customers
the new accommodation service ‘product’ is linked to the accommodation
the new accommodation service ‘room’ dictionary ‘code’, ‘name’, and ‘class’ values match that of the accommodation ‘rooms’ list item
a new invoice is created and listed under the booking’s invoices sub-resource
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 departuredeparture 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
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
see first: Confirming a Departure Service
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
a departure service with ‘status’ “Confirmed”
the departure service ‘product’, is a departure with an
addons
item of type “transports”the departure service ‘product’, is a departure with ‘availability.status’ not equal to “REQUEST_SPACE”
the transport has an ‘availability.status’ of “AVAILABLE”
the number of departure service existing customers is less than or equal to the value of the transport ‘availability.status.total’
the ‘start_date’ and ‘finish_date’ being booked must be within the ‘start_date’ and ‘finish_date’ of one of the transport ‘season_dates’ for the ‘price_bands’ list item
the ‘start_date’ and ‘finish_date’ being booked can not be within the ‘start_date’ and ‘finish_date’ of one of the transport ‘blackout_dates’ for the ‘price_bands’ list item
the number of departure service existing customers must be within the ‘min_travellers’ and ‘max_travellers’ of one of the transport ‘price_bands’ list item
the existing departure service’s customers must be within the ‘min_age’ (if not null) and ‘max_age’ (if not null) of one of the transport ‘price_bands’ list item
Postconditions
new transport service is created and listed under the booking services sub-resource
the new transport service has ‘status’ “Confirmed”
the new transport service has ‘status_transitions’ [“Request Cancellation”]
the new transport service has ‘start_date’ and ‘finish_date’ matching the ‘start_date’ input values (should be the same)
the new transport service ‘customers’ list is the same as the departure service
the new transport service has an ‘date_confirmed’ with the current date/time
the new transport service has a null ‘option_expiry_date’
the new transport service ‘purchase_price’ matches the currency-specific price listed in the transport (as per preconditions), multiplied by the number of customers
the new transport service ‘product’ is linked to the transport
the new transport service ‘pickup_time’ and ‘flight_number’ are not null
a new invoice is created and listed under the booking’s invoices sub-resource
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:
Costa Rica Adrenaline Theme Pack (see ‘addons’ for a departure of tour dossier example: CRQ Tour Dossiers)
Antarctica Kayaking, Antarctica Camping (see ‘addons’ for a departure of tour dossier example: XVCASX Tour Dossiers)
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
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
see first: Confirming a Departure Service
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
a departure service with ‘status’ “Confirmed”
the departure service ‘product’, is a departure with an
addons
’ item of type “activities”the departure service ‘product’, is a departure with ‘availability.status’ not equal to “REQUEST_SPACE”
the activity has an ‘availability.status’ of “AVAILABLE”
the number of departure service existing customers is less than or equal to the value of the activity ‘availability.status.total’
the number of departure service existing customers must be within the ‘min_travellers’ and ‘max_travellers’ of one of the activity ‘price_bands’ list item
the existing departure service’s customers must be within the ‘min_age’ (if not null) and ‘max_age’ (if not null) of one of the activity ‘price_bands’ list item
Postconditions
a new activity service is created and listed under the booking services sub-resource
the new activity service has ‘status’ “Confirmed”
the new activity service has ‘status_transitions’ [“Request Cancellation”]
the new activity service has ‘start_date’ and ‘finish_date’ match those of the activity
the new activity service ‘customers’ list is the same as the departure service
the new activity service has an ‘date_confirmed’ with the current date/time
the new activity service has a null ‘option_expiry_date’
the new activity service ‘purchase_price’ matches the currency-specific price listed in the activity (as per preconditions), multiplied by the number of customers
the new activity service ‘product’ is linked to the activity
a new invoice is created and listed under the booking’s invoices sub-resource
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
see first Holding an Option on a Non-Rooming Departure and Holding an Option on a Rooming Departure
see first: Confirming a Departure Service
a booking with a null ‘date_closed’
a booking with a ‘date_of_first_travel’ that is in the future
a departure service with ‘status’ “Confirmed”
the departure service ‘product’, is a departure with an
addons
item of type “single_supplements”the departure service ‘product’, is a departure with ‘availability.status’ not equal to “REQUEST_SPACE”
the departure service ‘rooms.code’ matches that of the single supplement ‘rooms’ item ‘code’ for the single supplement service
the single supplement has an ‘availability.status’ of “AVAILABLE”
the number of departure service existing customers is less than or equal to the value of the single supplement ‘availability.status.total’
the number of departure service existing customers must be within the ‘min_travellers’ and ‘max_travellers’ of one of the single supplement ‘price_bands’ list item (i.e. only one customer on the departure service
the existing departure service’s customers must be within the ‘min_age’ (if not null) and ‘max_age’ (if not null) of one of the activity ‘price_bands’ list item
Postconditions
a new single supplement service is created and listed under the booking services sub-resource
the new single supplement service has ‘status’ “Confirmed”
the new single supplement service has ‘status_transitions’ [] (at this time it is not possible to Cancel single supplement service via the API)
the new single supplement service has ‘start_date’ and ‘finish_date’ match those of the related departure service
the new single supplement service ‘customers’ list is the same as the departure service
the new single supplement service has a ‘date_confirmed’ with the current date/time
the new single supplement service has a null ‘option_expiry_date’
the new single supplement service ‘purchase_price’ matches the currency-specific price listed in the single supplement (as per preconditions), multiplied by the number of customers
the new single supplement service ‘product’ is linked to the single supplement
a new invoice is created and listed under the booking’s invoices sub-resource