Skip to main content

ExchangeBookingRQ

Exchange Booking - REST

Exchange Booking - SOAP

Features in the ExchangeBookingRQ API include:

  • Updates the itinerary and creates a Price Quote Reissue Record for a ticket exchange in a single API call
  • Capability to specify a price tolerance threshold for the Automated Exchanges Comparison response
  • Returns details of the generated Price Quote Reissue record
  • Manages sessions on behalf of the client application
  • Ensures the successful issuance of a PQR with error handling

Workflow

Exchange Booking RQ

The API performs a number of steps to issue a PQR:

  • Ignores the transaction to ensure that the AAA is clear
  • Retrieves the existing reservation using the record locator provided within the payload
  • Cancels specified PNR air segments
  • Books new segments
  • Performs an automated exchanges comparison call
  • Performs an automated exchanges confirmation call
  • Commits the newly generated PQR into the PNR
  • Depending on input, retrieves PQR details and/or retrieves full reservation details
  • Ignores the transaction after the transaction to ensure that the AAA is clear

Single PQR Strategy

A single PQR is generated by sending a single instance of the /ExchangeBookingRQ/AutomatedExchanges element.

Main Flow

Depending on your input, the API will:

  • Cancel specific air segments (/ExchangeBookingRQ/Cancel)
  • Add new segments to the reservation (/ExchangeBookingRQ/AirBook)
  • Keep specific segments unchanged (/ExchangeBookingRQ/Itinerary/SegmentPricing)

The API will then automatically select segments to be passed onto the Automated Exchanges comparison step using the logic below:

  1. If you want to keep the segments unchanged, the numbers of the segments must be specified with the /ExchangeBookingRQ/Itinerary/SegmentPricing element. The specified segments will be automatically sent to Automated Exchanges.

  2. To re-book segments, specify the segments to be canceled and re-booked using the ExchangeBookingRQ/Cancel and …/AirBook elements. The specified segments will be automatically sent to Automated Exchanges.

Note: Activation of the Travel Journal Record (TJR) component for the Auto Segment Arrangement is expected. This determines the ability to automatically order the segments in the itinerary after canceling and rebooking.

  1. To modify segments (modify booking class, date, origin, and destination), specify the segments in the ExchangeBookingRQ/Cancel and …/AirBook elements. The specified segments will be automatically sent to Automated Exchanges.

Note: Activation of the Travel Journal Record (TJR) component for the Auto Segment Arrangement is expected. This determines the ability to automatically order the segments in the itinerary after canceling and rebooking.

  1. To validate that the total amount for an exchange matches a specific price threshold, amounts passed by the ExchangeShopping response use the …/AutomatedExchanges/PriceComparison element.

Note: If the acceptable threshold is not met, ExchangeBookingRQ will stop processing and return a corresponding error message (refer to the Error Handling section of this guide).

If the amount matches the specified threshold, the API will move on to the Automated Exchanges confirmation step to complete the exchange. At this point, the PQR will be committed to the face of the PNR via an end transaction call.

The response will contain the generated PQR number by default in the /ExchangeBookingRS/ExchangeConfirmation/@PQR_Number element.

Depending on the values entered, the service response may include full PQR details in /ExchangeBookingRQ/PostProcessing/@returnPQRInfo="true" or full reservation details in /ExchangeBookingRQ/PostProcessing/@redisplayReservation="true".

Multiple Ticket Exchanges for Exchange Booking

Starting June 2022 ExchangeBookingRQ began supporting exchanges for multiple tickets/passengers. Since the existing request schema (for both versions 1.0.0 and 1.0.1) already supports multiple repetitions of /ExchangeBookingRQ/AutomatedExchanges there is no version upgrade required to take advantage of this functionality.

Additional Schema Changes

The request schema introduces a new attribute /ExchangeBookingRQ/@multipleExchangesWaitInterval, letting the user control the application delays between subsequent ticket exchange operations.

Note: We recommend setting the interval value at 2500 milliseconds or more; however the schema permits values between 1000 and 10000 milliseconds.

The response schema was slightly altered in support of multiple Price Quote Reissue (PQR) records at /ExchangeBookingRS/ExchangeConfirmation. Each instance of the element will pass the information on a separate PQR.

Business Logic Changes

There are no changes for single-ticket exchanges. The business process as well as error handling remains as it was. Business logic changes for multiple ticket exchanges can be illustrated by the flowchart below:

Exchange Booking Multiple Calls

Note: If there are multiple ticket exchanges, the API considers a transaction successful if a single Price Quote Reissue Record (PQR) is generated. For example, if you wish to exchange three tickets and at least one of them is successfully processed, the API will return a success message. The message will be supplemented with additional warnings indicating failure reasons for other ticket numbers.

Example:

<SystemSpecificResults>
    <Message code="WARN.SP.PROVIDER_ERROR">Exchange Booking failed for ticket number 0017862313255 with Cause: Unable to perform automated exchanges confirmation step. Comparison step did not generate PQR Number</Message>
</SystemSpecificResults>

The API response will indicate an error only when all tickets fail.

Version 1.1.0 Changes

Reservation Segment Handling

Previous versions of Exchange Booking (1.0.0 and 1.0.1) would automatically send all PNR segments for Automated Exchange comparison pricing, including segments specified in /ExchangeBookingRQ/Itinerary/SegmentPricing and any others residing in the reservation.

This logic works for simple use cases, but we found it can be problematic in the scenarios below:

  • The PNR contains a mixture of products (flights with hotels, other segments, or vehicles). In this case, automatic segment selection does not take non-air segments into consideration, and returns an INVLD ITIN error.
  • The PNR contains a multi-ticket itinerary, but only a specific flight segment on a single ticket needs to be exchanged.
  • The PNR contains a surface segment or a break in the itinerary (ARNK). In this case, automated segment selection does not take these segments into consideration and returns an INVLD ITIN error.

Version 1.1.0 addresses each of the scenarios above:

  • If the PNR contains a mixture of products, it will not be possible to specify a non-air PNR segment within /ExchangeBookingRQ/Itinerary/SegmentPricing. Also, it will not be possible to send non-air PNR segments for cancellation. This ensures that the PNR changes (retain, cancel, add) apply only to flight segments.

  • New validation errors were added:

    /ExchangeBookingRQ/Itinerary/SegmentPricing/SegmentSelect/@Number=___ is not an air segment ExchangeBookingRQ/Cancel/Segment/@Number cannot be non-air reservation segment

  • The API will no longer send all PNR segments for Automated Exchanges Comparison pricing. You can now decide which flights will be part of the actual exchange process! In the new version, the service will only exchange segments that:

    • Were determined by you to be kept with /ExchangeBookingRQ/Itinerary/SegmentPricing
    • Were added to the PNR by means of /ExchangeBookingRQ/AirBook

    All other segment types will not be considered.

  • The API now manages surface segments (ARNKs) automatically on your behalf:

    • If the PNR contains any ARNK segments, the segments will be removed at the beginning of the API workflow.
    • Once the API makes all the changes to the PNR (cancel, book, process Automated Exchanges Comparison and confirmation), ARNK segments will now be added automatically if needed.

Other Changes

  • Added a main error message to be returned at:

    /ExchangeBookingRS/ApplicationResults/Error/SystemSpecificResults/Message

    <Message code="ERR.SP.PROVIDER_ERROR">No new price quote reissue (PQR) records have been stored, see remaining messages for details.</Message>

    In case there is a service failure, this will be the only Error element returned by the API. All other complementary messages will be returned within Warning nodes.

  • From now on, the service response will only contain newly created Price Quote Reissue Record (PQR) information. If there were any other PQR records linked to the PNR prior to the transaction, these will not be returned at /ExchangeBookingRS/PriceQuoteReissue.

  • The Automated Exchanges (AutomatedExchangesLLSRQ) Sabre-internal API was updated from version 2.6.1 to 2.9.0, and as a result, the request schema for Exchange Booking now contains the following additions:

    • New attribute: /AutomatedExchangesRQ/ExchangeComparison/ExchangeOverrides/@ExcludeFeeOnPenaltyTax
    • The element /AutomatedExchangesRQ/ExchangeComparison/ExchangeOverrides/FeeOnPenalty/Tax changed the repeat factor from 2 to 3
    • New element: /AutomatedExchangesRQ/ExchangeComparison/ExchangeSegment/PriceRequestInformation/OptionalQualifiers/PricingQualifiers/SpecificFareBasis
    • Element /AutomatedExchangesRQ/ExchangeComparison/PriceRequestInformation/OptionalQualifiers/PricingQualifiers/Account/Code changed the repeat factor from 0 to 4
    • Element /AutomatedExchangesRQ/ExchangeComparison/PriceRequestInformation/OptionalQualifiers/PricingQualifiers/Corporate/ID changed the repeat factor from 0 to 4
    • New element: /AutomatedExchangesRQ/ExchangeComparison/PriceRequestInformation/OptionalQualifiers/PricingQualifiers/RetailerRuleQualifier
    • New element: /AutomatedExchangesRQ/ExchangeComparison/PriceRequestInformation/OptionalQualifiers/PricingQualifiers/SpecificFareBasis
    • New element: /AutomatedExchangesRQ/ExchangeComparison/PriceRequestInformation/OptionalQualifiers/PricingQualifiers/ExcludeBookingCode
    • New element: /AutomatedExchangesRQ/ExchangeComparison/PriceRequestInformation/OptionalQualifiers/PricingQualifiers/SpecifyMaxPenalty

Error Handling

The table below illustrates error handling for Exchange Booking:

Location Scenario Error Message
Schema RQ Request schema validation has failed; invalid input. SOAP Fault in response with schema validation details.
Request validation The same segment numbers were in SegmentPricing/SegmentSelect/@number and Cancel/Segment/@Number. This is telling the API to price and cancel the same itinerary segment. ExchangeBookingRS with Business error: "/ExchangeBookingRQ/Itinerary/SegmentPricing/SegmentSelect/@Number and /ExchangeBookingRQ/Cancel/Segment/@Number cannot be the same"
GetReservation – initial call Error in response or connection issue ExchangeBookingRS with Business error: "Unable to retrieve reservation – see below messages for details” Warnings (Provider error): with details, GetReservation error as warning
GetReservation – initial call Client chose to price non-air segments ExchangeBookingRS with Business error: /ExchangeBookingRQ/Itinerary/SegmentPricing/ SegmentSelect/@Number= is not an air segment
GetReservation – after cancel and book steps Error in response or connection issue ExchangeBookingRS with Business error: "Unable to retrieve reservation details after cancel and booking steps – see below messages for details" Warnings (Provider error): with details, GetReservation error as warning
GetReservation – after cancel and book steps No new flight segments to price. ExchangeBookingRS with Business error: "No newly created flight segments available for Automated Exchanges pricing after Cancel and AirBook steps"
GetReservation – final optional call Error in response or connection issue. ExchangeBookingRS with a business warning: "Unable to redisplay reservation after PQR creation – see below messages for details" Warnings (Provider error): with details, GetReservation error as warning
Price Comparison Exchange cost value not returned from AutomatedExchangesLLSRQ comparison step response. ExchangeBookingRS with business error: "Unable to perform price comparison - total amount for exchange was not returned by the low-level service."
Price Comparison Price above the threshold specified by the customer when haltOnNonAcceptablePrice is true ExchangeBookingRS with business error: "Automated Exchanges comparison TotalRefund the amount is over the specified limit for .../ExchangeBookingRQ/AutomatedExchanges[< VALUE>]/PriceComparison"
Price Comparison Price above the threshold specified by the customer when haltOnNonAcceptablePrice is false ExchangeBookingRS with a business warning: "Automated Exchanges comparison TotalRefund amount is over the specified limit for .../ExchangeBookingRQ/AutomatedExchanges[< VALUE>]/PriceComparison"
Price Comparison Price below the threshold specified by the customer when haltOnNonAcceptablePrice is true ExchangeBookingRS with Business error: "Automated Exchanges comparison TotalRefund amount is under the specified limit for .../ExchangeBookingRQ/AutomatedExchanges[< VALUE>]/PriceComparison”
Price Comparison Price below the threshold specified by the customer when haltOnNonAcceptablePrice is false ExchangeBookingRS with a business warning: "Automated Exchanges comparison TotalRefund amount is under the specified limit for .../ExchangeBookingRQ/AutomatedExchanges[< VALUE>]/PriceComparison”
AutomatedExchanges – confirmation call The PQR_Number attribute value is not returned by the AutomatedExchangesLLSRQ comparison step response. ExchangeBookingRS with Business error: "Unable to perform automated exchanges confirmation step. The comparison step did not generate PQR Number”
Retrieval of Price Quote details DisplayPriceQuoteLLSRQ error in response or connection issue ExchangeBookingRS with a business warning: “Unable to retrieve PQR information - see below messages for details”
Automated Exchanges - multiple ticket exchanges All ticket exchanges failed ExchangeBookingRS with a business error: “Unable to perform automated exchanges. See below messages for details”
Automated Exchanges - multiple ticket exchanges One of the ticket exchanges failed ExchangeBookingRS with a business warning: “Exchange Booking failed for ticket number %s with Cause"
Enhanced End Transaction Commit PQR to the PNR record ExchangeBookingRS with a business error: “Unable to commit PQR number to the reservation. End transaction step has failed, please review the messages below."
Display Price Quote Reissue Record Retrieve PQR details ExchangeBookingRS with a business warning: “Unable to retrieve PQR information – see below messages for details"
Main Error General API Failure ExchangeBookingRS with a provider error: “No new price quote reissue (PQR) records have been stored, see remaining messages for details."