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:
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:
- Create a trip in the Gordian system.
-
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. -
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:
- Add new products to the basket.
- Replace the basket items with a new set of products.
- Replace the basket items of a certain product type with a new set of products.
- Replace the basket items of a certain passenger with a new set of products.
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 invalid_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:
- Start a basket check.
- 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.
- If the updated state is
Book ancillaries
To book the ancillaries in the basket:
- Update the trip information with all pending details such as record locator.
- Review the contents of the basket by polling the basket contents.
-
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. -
Confirm that the customer sees the final price before proceeding.
- Charge the customer’s form of payment.
- If the customer is not paying before the
valid_until
date, repeat step 1.
- If the customer is not paying before the
-
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. -
Poll the trip information endpoint to see the status of the fulfillment.
- Each of the products in the
orders
object has its own status.
- Each of the products in the
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:
- Use the same
trip_id
of the trip you registered. - Start a check of the trip.
- 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.
- Each of the products in the
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:
- Use the same
trip_id
of the trip you registered. - Search for products
- The prices in the search results are the cost of changing, not the base prices.
- 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 ownrefund_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:
- Start a cancellation check for every product in the booking.
- 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.
- Confirm cancellation. Starts the cancellation with the airline.
- Poll the trip information endpoint to see the status of the cancellation.
- Each of the products in the
orders
object has its own status.
- Each of the products in the
Tip
Subscribe to the Cancellation Completed callback to receive a notification with the final state of the process.