Skip to content

Flights

Use the Gordian API to enable a full customer journey that includes the following:

  1. Search for flights
  2. Add products to the basket
  3. Confirm passenger details
  4. Book a flight

Additionally, you can enable the customer to do the following actions :

Important

This tutorial assumes that you already have your API key and have selected the authentication and authorization methods to use the Gordian API. For more information, see the getting started guide.

Search for flights

The first step of the journey is when the customer wants to search for flight options. To search for flights:

  1. Create a trip in the Gordian system.
  2. Start a search request with the origin and destination.

    Tip

    Do steps 1 and 2 at the same time by using the search object in the create trip call.

  3. Poll the search results endpoint until you get ticket options. The search results include a complete list of the benefits of each of the fares, including cancellation, modifications, and included baggage.

Search for options

A search for all results has the cheapest few fares for each itinerary. To get more results for a specific date, place, or flight, add search parameters in the journeys object. The more specific the values are, the higher the priority in the search. For example, see the following JSON object for starting a search request:

{
  "ticket": {
    "search": true,
    "cabin_class": "economy",
    "detailed_results": 1,
    "group_by": "itinerary",
    "journeys": [
      {
        "arrival_city": "LON",
        "arrival_date": "2020-07-07",
        "departure_airport": "EDI",
        "departure_date": "2020-07-07",
        "segments": [
          {
            "flight_number": "1523",
            "marketing_airline": "WN"
          },
          {
            "flight_number": "125",
            "marketing_airline": "WN"
          }
        ]
      },
      {
        "arrival_airport": "EDI",
        "arrival_time": "2020-04-24T10:10:00+00:00",
        "departure_airport": "LGW",
        "departure_date": "2020-07-14",
        "segments": [
          {
            "flight_number": "205",
            "marketing_airline": "WN"
          },
          {
            "flight_number": "1620",
            "marketing_airline": "WN"
          }
        ]
      }
    ],
    "order_by": "price"
  }
}

The segments objects define specific flight numbers of interest to the customer. In this case, the flight_number value has a higher priority in the search process than the rest of the parameters.

Add products to the basket

To provide accurate prices to your customer, make sure to add the tickets to the Gordian basket. You have multiple ways to add tickets:

Once a ticket is in the basket, the basket information keeps a validity field for each item, and it may be one of the following values:

  • checking: Gordian is checking the fare. Continue to poll the basket information endpoint for an updated state.
  • valid: Gordian holds the ticket to ensure they are available for your customer.
  • price_changed: There has been a price change since the last time it was checked.
  • needs_check: The date in valid_until has passed and the fare needs a check.
  • unavailable: The fare is no longer available.

If the customer’s session is open for a long time, or you check the basket items later, the fares may no longer be valid. To verify the fares of products already in the basket:

  1. Start a basket check.
  2. Poll the basket information endpoint until you receive the updated state.
    • If the new validity value is price_changed, re-adding the same product to the basket accepts the changed price.

Add Ancillaries

Each ticket has included ancillaries that are part of the search results. To offer the customer the ability to purchase additional ancillaries, follow these steps:

  1. Add the ticket to the basket to make sure Gordian checks and holds the ticket.
  2. Start a new search selecting search results only for ancillaries.
    • You can only search for ancillaries after a ticket is in the basket.
  3. Get the search results and present them to the customer.
  4. Put the selected ancillaries in the basket. This is the same procedure as with flight tickets.

Tip

Gordian provides a Dynamic Upsell widget to easily integrate a UI in your customer journey to offer ancillaries.

Confirm passenger details

As soon as you have the full information of the passengers, do the following:

  1. Update the trip with the information including contact address and date of birth.
  2. Check the response for any changes in the basket to inform the customer. For example, price drops due to loyalty program information.

Book a flight

When the customer is ready to book a flight, follow these steps:

  1. Review the contents of the basket by polling the basket information.
  2. Confirm that all the products in the basket have the status of valid.

    • If the products have other status values, proceed as follows:
    Status value Action item
    checking Poll the basket information endpoint until the check is complete.
    invalid Start a check of the basket to refresh validity.
    unavailable Inform the customer and possibly give them the option to select alternatives.
    price_changed Inform the customer and possibly give them the option to select alternatives.
  3. Confirm that the customer sees the final price before proceeding.

  4. Charge the customer’s form of payment.
    • If the customer is not paying before the valid_until date, repeat step 1.
  5. Send the fulfillment request.

    Security note

    Include the trip_state_hash received from step 1. The hash represents the state of the trip at that specific moment in time, ensuring that there wasn't any change to the basket between step 1 and 4.

  6. Poll the trip information endpoint until you see the status of the fulfillment.

    • Each of the products in the orders object has its own status.

Tip

Subscribe to the Fulfillment Completed callback to receive a notification with the final state of the process.

Change a booking

When the customer wants to change a booking, follow these steps:

  1. Use the same trip_id of the trip which already has tickets booked.
  2. Search for products
    • The prices in the search results are the cost of changing, not the base prices.
  3. Proceed with checking and booking changes using the same flow as the initial search.

Check a booking

Airlines may change bookings without necessarily informing the customer. You can start a check of all the items in a booking with the following steps:

  1. Use the same trip_id of the trip you registered.
  2. Start a check of the trip.
  3. Poll the trip information endpoint until the state is no longer check_in_progress.
    • Each of the products in the orders object has its own status.

Tip

Subscribe to the callbacks to receive a notification with the final state of the checking process.

Involuntary changes

If you subscribed to notifications, you receive a callback in the event of the following involuntary changes:

  • involuntary_change: there is no action to be taken by the customer. For example, the schedule changed by a small amount.
  • involuntary_cancellation: The product has been cancelled and refunded. Each product has its own refund_amount property.
  • customer_action_needed: the customer must choose an option:
    • Get a refund. They can proceed through the cancellation process.
    • Select an alternative. The customer must select an alternative from a list. Add the selection to the basket and fulfill. If the booking has ancillaries and there was a change, you receive an involuntary_change callback.

Cancel a booking

When the customer wants to cancel a booking, follow these steps:

  1. Start a cancellation check for every product in the booking.
  2. Poll cancellation details endpoint to get the results of the check. It includes the refund amount for the products and each product that would be cancelled with it, for example, seat or bag selection.
  3. Confirm cancellation. Starts the cancellation with the airline.
  4. Poll the trip information endpoint to see the status of the cancellation.
    • Each of the products in the orders object has its own status.

Tip

Subscribe to the Cancellation Completed callback to receive a notification with the final state of the process.