Exchanging an Air Booking
The steps below explain how to exchange or modify an existing air booking for a traveler. All APIs mentioned below are dependent on each other and the steps described here must be executed in the order specified.
Notes:
- You can exchange a leg or add a new leg within an existing ticket. To learn more, view the Leg section of Basic air concepts.
- You can only initiate an exchange for a ticket which has been confirmed. (i.e.,
bookingStatusfor the PNR isCONFIRMED_STATUS). You can check your PNR status using the Get PNR API.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| 1. | Get PNR exchange details | /v2/air/pnrs/{pnrId}/exchange-details | View the exchange-related information for the tickets inside a PNR. This endpoint displays information such as whether exchanges or refunds are allowed. Request body requires: pnrId from Step 10 of the Making an Air Booking Workflow. Response will contain: pnrId and the details for the ticket that needs to be exchanged. |
| 2. | Modify search | v2/air/modify-search | If your ticket can be exchanged (based on the response from Step 1), use this endpoint to search for a different itinerary. Request body requires: pnrId from Step 10 of the Making an Air Booking workflow, legs (1), search filters, sort options, and leg search parameters(2). Response will contain: searchId for this new search and itineraryId for each itinerary returned in the search results. Other APIs will use: searchId itineraryId |
| 3. | Get selected itinerary | /v2/air/selected-itinerary | View one selected itinerary and its respective details. Request body requires: searchId and itineraryId from Step 2. Response will contain: Itinerary details for the itineraryId provided in the request. |
| 4. | Get flight checkout details | /v2/air/flight-checkout | Get checkout related information for a selected itinerary from Step 3. Request body requires: searchId and itineraryId from Step 2. Response will contain: checkoutResponseId, baggage information, ancillaries, checkout parameters, and supported payment options. Other APIs will use: checkoutResponseId |
| 5. | Get flight seat map | /v2/air/seat-map | View the seat map for the selected itinerary from Step 3. Request body requires: airItineraryId (an object wrapper containing both searchId and itineraryId from Step 2) and traveler information. Response will contain: seatMapResponseId Other APIs will use: seatMapResponseId |
| 6. | Validate air itinerary | /v2/air/revalidate-itinerary | Validate the selected itinerary to finalize your booking. Request body requires: checkoutResponseId from Step 4, seatMapResponseId from Step 5, paymentSourceId(3), tripId, traveler details, and booking charges. Response will contain: bookingId, fare breakdown, leg prices, and policy details. Other APIs will use: bookingId |
| 7. | Modify booking | /v2/air/modify-book | Book new legs or modify legs in an existing PNR. Request body requires: bookingId from Step 6 and tripId. Response will contain: pnrNumber, pnrId, and pnrStatus. |
The PNR status for the exchanged or modified ticket will be returned in Step 7. You can also use the Get PNR API to check the PNR status again.
Note: Since we are making changes to an existing trip, the
tripIdwill remain the same from Make an Air Booking Workflow. During the booking exchange process, use the sametripIdyou’ve generated in Step 7 from Make an Air Booking Workflow.
Additional Notes
(1) In Step 2, the legs will be indexed in the order you want your final itinerary to be. You can modify an existing leg and add a new leg simultaneously. However, you cannot remove an existing leg.
(2) In the leg search parameter, you'll need to provide the searchId obtained from Step 1 of the Making an Air Booking Workflow.
(3) Contact your Spotnana representative to obtain the paymentSourceId.