Introduction

Confirming Services¶

Now that you’ve made your first booking, we can move onto more advanced topics. In this tutorial, we’ll cover the idea of auto confirmation. Specifically, we’ll understand the workflow that is necessary to Confirm a booking, and how to gracefully revert to an Option (Held) service without damaging the customer experience.

Ideal Implementation For Simplicity

When creating services, the status of a service is defined by our reservation system. Upon creating of a service, it is likely it’ll be in an Option state. Upon being returned a service object, you’ll be provided the list of requirements necessary to complete to ensure the service can enter a Confirmed state.

For this tutorial, we’ll assume all services we create are initially set as Option, and then inspect the response data from the G Adventures API to ensure our system understands what to do next.

Generally, most products can be confirmed at time of booking, if sufficient details were provided by the customer. There are exceptions to this rule, around products which require Visas, Medical Forms, or other signed documents. These can be fulfilled within our Good To Go product.

Let’s work through the steps necessary to auto-confirm a service. Additionally, we’ll cover the case where one cannot auto-confirm, so you can understand how to identify it, and have your system respond appropriately to the customer.

Confirming A Service

Before we can book a service, there’s some scaffolding that needs to be in place. You’ll need a booking, and a customer. If you haven’t already, please do read Creating Your First Booking, which will ensure you understand that workflow.

Assuming you have those, you should be able to create a Departure Service. Here’s an example of the POST request to create one, along side the response, snipped for focus.

We picked a random available departure, from one of our Highlights of Sabah & Mt. Kinabalu tour for this example.

POST /departure_services/ HTTP/1.1

{
    "customers": [
        {"id": "3250302"}
    ],
    "product": {"id": "776988"},
    "booking": {"id": "1123929"}
}

And the response:

{
        "id": "2282970",
        "href": "https://rest.gadventures.com/departure_services/2282970",
        "name": "Highlights of Sabah & Mt Kinabalu",
        "status": "Option",
        "status_transitions": [
                "Expired"
        ],
        "type": "departure_services",
        "incomplete_requirements": [
                {
                        "type": "CONFIRMATION",
                        "name": "Nationality",
                        "code": "NATIONALITY",
                        "message": "Nationality must be submitted for this product. 'nationality' must be set in the customer resource.",
                        "flags": [],
                        "details": [],
                        "customer": {
                                "id": "3250302",
                                "href": "https://rest.gadventures.com/customers/3250302",
                                "name": {
                                        "legal_first_name": "Bartek",
                                        "legal_middle_name": null,
                                        "legal_last_name": "Ciszkowski",
                                        "common_name": null,
                                        "title": "Mr"
                                }
                        }
                },
                {
                        "type": "CHECKIN",
                        "name": "Arrival Flight Details",
                        "code": "ARRIVAL_FLIGHT_DETAILS",
                        "message": "Arrival flight number, date, and time are required for this product.",
                        "flags": [],
                        "details": [],
                        "customer": {
                                "id": "3250302",
                                "href": "https://rest.gadventures.com/customers/3250302",
                                "name": {
                                        "legal_first_name": "Bartek",
                                        "legal_middle_name": null,
                                        "legal_last_name": "Ciszkowski",
                                        "common_name": null,
                                        "title": "Mr"
                                }
                        }
                }
        ]
}

There are three important attributes we must consider when reviewing this response. This is where you can design your system to get smart about how it handles auto-confirmation when booking services. Let’s consider these fields:

status - Contains the current status of the departure service. When creating a new one, the status is generally implicitly set to Option when possible (Other statuses are possible too, ensure you read the full departure service documentation for that)
status_transitions - Contains the possible statuses you can transition this service to via a PATCH request. Notice that in this case, there is no Confirmed listed here. We’ll get to that in a bit.
incomplete_requirements - Details the requirements left to either Confirm, or Checkin to the trip. For the purposes of this exercise, we’ll focus on those requirements with the type set to CONFIRMATION.

Now, we need to design a system that can confirm from this Option state. If the status_transitions contains Confirmed, that means we can PATCH this Departure Service with a change in status and it’ll confirm as expected.

However, in this case, that is not available, so we must inspect the incomplete_requirements. Reviewing this list, we see that the single CONFIRMATION type that is missing, is Nationality. Each of these incomplete requirements has a code, which you can map back to your system.

In this case, the missing requirement maps back to a single field, and points you to the customer missing this requirement. Note that because a service can have more than one customer, the Nationality requirement can show up multiple times, for each customer missing that data. In other situations, the missing requirement may point to multiple fields or a separate process (e.g. Medical Form, Arrival Flight Details). These can be required for CONFIRMATION, and you can identify those by mapping their codes in your system. This way, if you identify a requirement you know you cannot fulfill within your booking workflow, you can push that fulfillment to a separate process, later in the funnel. Additionally, most complex requirements are only necessary for CHECKIN, and the trip can be confirmed prior to those being completed.

Let’s review. We now need to adjust this services customer data to allow for confirmation. What would we do?

We PATCH the appropriate customer(s) with the missing CONFIRMATION data. If your online booking process asks for Nationality, and you have it, you can ensure the customer is created with that data. If not, you could always revert back to the customer to request more details, letting them know they are moments away from confirming their tour.
Upon adjusting the customer data, the incomplete_requirements for the Departure Service will be adjusted, and the status_transitions would be updated to make Confirmed available as a status you can transition to.
Thus, you could now PATCH the departure service with the new Confirmed state.

All said and done, we do recommend always going the simplest route. Create an initial service with the details you believe your customers are willing to fill out, and allow our suite of communication tools, and Good To Go to help the customer, and your staff fulfill the rest of the requirements, thus enabling the confirmation of the trip.

For additional help, or ensuring the success of your booking workflow, please do get in touch with our support team.