Skip to content

Ancillaries

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.

You can add seats, bags, or priority boarding to a flight booking that was not booked through Gordian. To offer ancillaries to the customer, follow these steps:

  1. Search for ancillaries
  2. Check ancillaries
  3. Book ancillaries

Additionally, you can do the following actions as needed:

Tip

The following processes are the same as in Flight booking. When you are able to book ancillaries, you can start selling flight tickets with minor modifications. Contact your account manager for more information.

Search for ancillaries

To search for ancillaries:

  1. Create a trip in the Gordian system.
  2. Start a search request selecting the option for ancillaries you want: seats, bags, or priority boarding.

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

The search results contain a complete list of the benefits, including a representation of the seat map so you can present all the prices to the customer.

Tip

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

Check ancillaries

To check an ancillary and prepare it for purchase, put it in the basket. You have multiple ways to add ancillaries to the basket:

Once an ancillary is in the basket, it has a validity tag that may be one of the following values:

  • checking: Gordian is checking the ancillary. Continue to poll the basket information for an updated state.
  • valid: Gordian holds the ancillary to ensure it is 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 ancillary needs a check.
  • unavailable: The ancillary is no longer available.

If the customer’s session is open for a long time, or you check the basket items later, the ancillaries may no longer be valid. To verify the ancillaries 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 updated state is price_changed, re-adding the same product to the basket will accept the changed price.

Book ancillaries

To book the ancillaries in the basket:

  1. Update the trip information with all pending details such as record locator.
  2. Review the contents of the basket by polling the basket contents.
  3. 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.
  4. Confirm that the customer sees the final price before proceeding.

  5. Charge the customer’s form of payment.
    • If the customer is not paying before the valid_until date, repeat step 1.
  6. 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.

  7. Poll the trip information endpoint to 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.

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.

Change a booking

To change an existing booking, follow these steps:

  1. Use the same trip_id of the trip you registered.
  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 process as before.

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.