Skip to content

Flight Booking

Welcome to the Gordian Flight API. You can use this API to sell flights and ancillaries, make changes to bookings, and see the current status of your customers' bookings.

In order to search for flights:

  1. First you should create a trip.
  2. Then send a search with the origin / destinations of that trip. Set the properties inside tickets and tickets.journeys.
  3. Poll the search results endpoint until you get ticket options

This includes a complete list of the benefits of each of the fares, including cancellation, modification and included baggage.

Fare Options

A search for all results will only have the cheapest few fares for each itinerary. To get all the possible fares for a specific itinerary, take the journey_ids from the itinerary in question and start another search and include the specific journey in the tickets element of the search object..

Fare Check - initial

In order to verify a fare, put it in the basket.

Once a ticket is in the basket, we will include a “validity” tag which tells you whether the fare is "valid" "checking" "price_changed" or "unavailable". “Valid” tickets are held by Gordian to ensure they are available for your customer.

If it is “checking” then you can poll the basket endpoint until it is either valid, price_changed or unavailable.

Adding to the basket will price the offer with the airline and put a hold on that price if it wasn’t done already at the search step.

Fare Check - later

After the “valid_until” date, the product will move into the “needs_check” validity status. If the customer’s session is open for a long time, or if they come back later, then you will need to handle this state. To initiate a check of all the products in the basket, call the check basket endpoint.

You should then poll the basket to get the updated state of the products in the basket.

If at any point the product has the status “price_changed”, re-adding the same product to the basket will accept the changed price.

Ancillaries

Each ticket will have included benefits associated with that ticket, as shown at the Search step above. To offer the customer the ability to purchase additional ancillaries on top of the ticket, you can run a second search. See the search endpoint and select the “ancillaries” example. You should run this search when there are tickets already in the basket.

You should add ancillaries to the basket in exactly the same way as you add tickets.

Confirm passenger details

As soon as you have full information about the passengers, including contact address and date of birth, update the trip. Check the response to see if anything has changed about the basket. The earlier you do this the better, so that you can inform the user if the updated information affects the validity of the basket (e.g. if loyalty program information causes the price to drop).

Book

In order to book the products in the basket:

  1. Confirm the contents of the basket (as in Fare Check) by getting the basket contents. Check all the products in the trip are in the “valid” state and present the final price to the user. You should handle other states similarly to when you did the Fare Check:

    • If they are in the “unavailable” or “price_changed” step, you will need to inform the user and possibly give them the option to select alternatives.

    • If they are “invalid”, call the check basket endpoint to refresh validity

    • If they are “checking”, poll the basket until the check is complete.

  2. If the customer hasn’t paid before the “valid_until” time, repeat step 1

  3. Charge the customer’s form of payment

  4. Send the fulfillment request. Security note: include the trip_state_hash from step 1. This will ensure that even if you are making API calls from the front end, nobody has made changes to the basket between step 1 and 4.

Once the fulfillment request has been sent you will receive a Fulfillment Completed callback (assuming you have subscribed to the callbacks) to receive the final state of the trip:

  • Each of the products in the “orders” section will have their own status, which you should check to see the complete state of the booking.

Cancel

The flow for cancelling a booking is:

  1. Start a cancellation check - initiate a check to see what the customer will receive in the case of a cancellation

  2. Get cancellation details - poll for the results of that check. This will include the refund amount for the requested product and each product that would be cancelled with it (e.g. seat, bag selection)

  3. Confirm cancellation

Once the cancellation message has been sent, we will process the cancellation and then send you a Cancellation Completed callback (assuming you have already subscribed to that callback event).

Each of the products in the “orders” section will have their own status, which you should check to see whether the cancellation succeeded or failed.

Change

To change a booking, use a Trip which already has tickets booked, and then search for flights.

  • The prices shown in the search results will be the cost of changing, not base prices

  • Proceed with checking / booking changes using the same flow as the initial search

Involuntary Change / Irregular Ops

You can subscribe to callbacks to hear about involuntary changes.

Depending on the callback, it will determine what to do next:

  • “Involuntary Change” - when there is no action to be taken by the user. E.g. when the schedule changes by only a small amount.

  • “Customer action needed” - there are alternatives which the user can select from. These are presented as a list of products, which you can add to the basket and fulfill.

    • If there are ancillaries attached to the booking, then there will need to be a two step process:

      1. Select the alternative ticket

      2. If any of the attached ancillaries change you will receive a “involuntary change” callback

    • If the customer would instead prefer a refund, they can proceed through the cancellation process

  • “Involuntary Cancellation” - The product has been cancelled and refunded

    • Each product with this status will have a “refund_amount” property containing the amount of the refund