Skip to content

Seats Only

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 this guide, we'll review how to add seats to a flight booking that wasn't created through Gordian initially.

In order to search for seats:

  1. First you should create a trip. Make sure to include the information about the flight from your other provider.
  2. Then send a search and select the “ancillaries” example.
  3. Poll the search results endpoint until you get seat options

This includes a representation of the seatmap so you can present a full seatmap full of priced seats to your customer.

Add to Basket

To prepare a seat for purchase, put it in the basket.

Once a seat 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.

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

    • 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. Ensure that you include the PNR and ticket information for the customer's flight. 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.

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.

  • “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