Air Merchandising Offer Availability

AirReqRsp.xsd

Air Merchandising Offer Availability

Merchandising Offer Availability queries the supplier (air carrier) to determine if Optional Services are available and applicable for selected air segments. This service can be used to search for Optional Services with or without the existence of a PNR. When the Air Merchandising Offer Availability request is sent without a PNR, the traveler data and segments are used to search for available Optional Services. When sent post-booking, the provider PNR is retrieved and if available, the frequent flyer and stored fare are used to get the correct price for an optional service.

Notes: 

Schema

Located in AirReqRsp.xsd:

How To

The Air Merchandising Offer Availability request AirMerchandisingOfferAvailabilityReq is used to search for optional services for selected itinerary segments, for multiple carriers and multiple providers: Galileo (1G), Apollo (1V), and Worldspan (1P).

  1. Enter the minimum data required for all carriers and providers. Either or both the AirSolution and HostReservation elements are required in the Offer Availability request for all carriers and providers.

    • AirSolution identifies the segment and passenger information. Air segment data can be obtained from a Low Fare Shopping, Air Pricing, or Air Availability response, or from the segments in the PNR.

      Within AirSolution, the following may be required:

      • /Search Traveler is used to send the names of the travelers in the booking and loyalty card information if applicable.

        • SearchTraveler @Code is required.

        • SearchTraveler/Name @First and @Last are required.

        • SearchTraveler is required in the request when HostReservation is sent. If HostReservation is sent without SearchTraveler an error is returned: SearchTraveler is missing in the request.

      • AirSegment specifies the air segment for which the optional services are being requested.

        • Note: Any optional elements in AirSegment can be submitted in a Merchandising Offer Availability request. They are not required and if included, do not have any impact on the Merchandising request.

        • The following attributes within AirSegment are required: Key, ArrivalTime, Carrier, DepartureTime, Destination, FlightNumber, Origin, and Group.

    • HostInformation identifies the host reservation.

      Within HostReservation, the following data is required:

      • @ProviderCode is the GDS or other provider code.
      • @ProviderLocatorCode is used to retrieve the host booking and obtain items such as ticket designators and frequent flyer.
      • @Carrier is the carrier providing the merchandising.
      • @CarrierLocatorCode is the locator of the provider reservation.

      Notes on sending one or both elements:

      • If a HostReservation is sent in the request, the booking is retrieved, and the air segments for the carrier defined in HostReservation are returned in the response. Available optional services are returned for the air segments of the carrier defined in the HostReservation, regardless of AirSegment sent in the request. Multiple HostReservation elements can be sent.

      • If a HostReservation is not sent in the request, the AirSegment elements sent in the request are used to price optional services.

      • Multiple HostReservation elements can be sent.

  2. For Galileo requests, you can ensure that the prices for optional services in the Air Merchandising Offer Availability response match the prices in the Air Pricing response by sending AirSolution/HostToken. By sending HostToken, the branded fare prices associated with air segments are returned. When sending HostToken, the response matches both prices and the number of optional services that are returned in the Pricing response.

    If HostToken is not included in the request, optional services are returned but the prices may not be accurate.

  3. Enter additional request data, depending on the supplier or provider requirements.

    • HostReservation @ETicket status may be required by some suppliers.

    • The language code can be specified in the AirMerchandisingOfferAvailabilityReq @LanguageCode attribute. Rich Content & Branding information is returned in the language specified in the request, if it is available. If the requested language is not available, the default language (English) is returned.

    • AirSolution/SearchTraveler/LoyaltyCard, as well as any loyalty cards in the booking, are used to determine the cost of the service. The LoyaltyCard @SupplierCode is the carrier that requires the information for the loyalty card. Some suppliers require a Loyalty Membership.

      • Important! While Loyalty Membership information is optional in the schema, and may not be technically required by some suppliers, it is strongly recommended that ALL requests include this information so that the supplier can return complete and valid response options for the specified traveler.

    • OfferAvailabilityModifiers can be used to specify the type of Optional Services desired. These Service types can be specified in the request using the optional ServiceType attribute, which has enumerated values.

      Enumerations in typeMerchandisingServices support options such as:

      • Paid seating options.

      • Paid baggage options.

      • In-flight amenities.

      • Trip insurance.

      • Paid seating optional services can also be specified by carrier, using the optional Carrier attribute.

    • Prior to Universal API Release 21.1.1, Air Merchandising Offer Availability returned ancillaries in the response regardless of EMD interline agreements between carriers. Release 21.1

      • Release 21.1.1 and later validates the EMD interline agreements and return ancillaries that are bookable in the response, thus preventing ancillary book failures for ancillaries where an agreement doesn’t exist.

      • The host token from the Air Price response must be included in the AMOA pre-book request to consume this functionality.

      • This is a limited release feature. Contact your Travelport representative for details.

    • MerchandisingPricingModifiers can be used to specify the type of Merchandising and Pricing Services desired:

      • Users can send /AccountCode, for corporate rewards discounts on paid seat ancillaries, in the Air Merchandising Offer Availability Request, as well as the Price, Seat Map, and Air Merchandising Fulfillment requests.

      • The Account Code is not returned in the shop or price responses, but is recorded to the Universal Record History (including @Code, @SupplierCode, and @Type): AirPricingInfo/AirPricingModifiers/AccountCodes/AccountCode.

  4. The Air Merchandising Offer Availability response returns optional services from different providers and carriers, as well as additional details within the optional service. The response contains a per-passenger/per-flight listing of available Optional Services for the selected itinerary.

  5. If Optional Services are available for the selected itinerary, one or more OptionalServices/OptionalService elements are returned. Items returned in the response provide details/rules for optional services, such as whether the optional service is commissionable or refundable.

    Information returned Description

    Type of optional service

    Returned in OptionalService @Type.

    Pricing

    OptionalService @TotalPrice indicates the combined value of the base price and taxes for the option in the supplier's currency for this itinerary.

    A TotalPrice value of [Currency]0.00 indicates that the Optional Services is free of charge. The TotalPrice value may be based on the total for the itinerary OR the option for an individual traveler depending on the @PerTraveler value. The PerTraveler attribute indicates whether or not the TotalPrice of the specified option applies to all travelers in the itinerary (False) or to each traveler in the itinerary (True).

    The TotalPrice returned in Optional Services with Type "PreReservedSeatAssignment" is not 100% accurate. For the accurate paid seat price, the Seat Map request SeatMapReq with ReturnSeatPricing="true" must be used. The prices displayed on the seat map validates the seat characteristics, hence it shows the accurate pricing. Seat price displayed in the AMOA/Ancillary catalog is not an accurate price and should not be compared for validation purpose with the prices displayed on the seat map.

    OptionalService @ApproximateTotalPrice is the TotalPrice value converted into the default currency of the traveler's or travel provider's profile.

    In the following example, the ApproximateTotalPrice is returned in USD rather than EUR, which indicates that the supplier returned the price in Euros, while the default currency of the point-of-sale is US dollars. 

    <air:OptionalService Type="PreReservedSeatAssignment" TotalPrice="EUR100.00" 
SupplierCode="KL" SequenceNumber="467250" ServiceSubCode="0B5" 
SSRCode="RQST" IssuanceReason="A" AssessIndicator="MileageOrCurrency" 
ProviderCode="1G" BasePrice="EUR100.00" ApproximateTotalPrice="USD130.77" 
ApproximateBasePrice="USD130.77" Taxes="EUR0.00">
	<com:ServiceData AirSegmentRef="16T"/>
	<com:ServiceData BookingTravelerRef="0T"/>
	<com:ServiceInfo>
		<com:Description>ECONOMY COMFORT</com:Description>
	</com:ServiceInfo>
	<com:Remark> KL 611 - EUR100.00 PER PASSENGER ECONOMY COMFORT </com:Remark>
	<air:EMD FulfillmentType="2" AssociatedItem="Flight" Booking="SSR"/>
	<air:AdditionalInfo Category="S7"/>
	<air:FeeApplication Code="4">Per Traveler</air:FeeApplication>
</air:OptionalService>

    The total fares, fees, and taxes for the optional services are returned in OptionalServices/OptionalServicesTotal. In Air v29.0 and greater:

    • ACH Low Cost Carriers or API carriers: OptionalServicesTotal is blank if there are no confirmed or fulfilled Optional Services. If any Optional Services are fulfilled or confirmed, the OptionalServicesTotal reflects these items.
    • ATPCO carriers: OptionalServicesTotal is always blank.

    Pre-reserved seats

    OptionalService/Remark typically indicates the price of a pre-reserved seat assignment.

    When the optional service type is “PreReservedSeatAssignment”, the OptionalService @Remark is returned with the following text:

    “[Carrier Code] [Flight Number] – [Currency Code] ##.## PER PASSENGER [Commercial Name].”

    Optional Baggage

    Optional service baggage information returns in a structured format so that customers can easily parse relevant information for travelers to make educated decisions on cost of checked bags. Release 20.2

    In an AMOA response, when baggage information returns:

    • @FirstPiece and @LastPiece identifies which of the paid baggage options available (for a given air element) is the first paid bag and which one the second, regardless of being from a no-bag fare or a bag-included fare in a structured format in the optional services.
    • @TotalWeight indicates the maximum allowed weight, and the value returns in a structured attribute in optional services, when returned in the response
    • The response clearly identifies price and currency of the bag in the optional services.
    • When number of pieces exists, keeps the current attribute @Quantity enabled and includes the maximum weight allowed in the optional services.

    For example,

    <air:OptionalServices>
     <air:OptionalServicesTotal/>
      <air:OptionalService Type="Baggage" TotalPrice="AUD27.70" SupplierCode="AR" PerTraveler="false" 
  CreateDate="2020-02-04T16:47:19.178+00:00" ServiceStatus="Offered" SequenceNumber="100000" 
  ServiceSubCode="02U" SSRCode="ASVC" Key="zhXJNACJ3BKA0HAAAAAAAA==" AssessIndicator="MileageOrCurrency" 
  InclusiveOfTax="true" InterlineSettlementAllowed="false" GeographySpecification="Portion" Source="MCE" 
  ViewableOnly="true" TotalWeight="46" ProviderCode="1G" Quantity="1" BasePrice="AUD27.70" 
  ApproximateTotalPrice="AUD27.70" ApproximateBasePrice="AUD27.70" Taxes="AUD0.00" 
  OptionalServicesRuleRef="zhXJNACJ3BKA1HAAAAAAAA==" FirstPiece="2" LastPiece="2">

    Optional service description

    OptionalService/ServiceInfo/Description provides a description of the service. Often, the MediaItem element is also returned with media URLs for the service. Release 17.3
    Is Reprice Required / C Type Baggage

    Prior to Universal API release 21.2.2, customers were limited to viewing prices and purchasing F type filed bags only. Release 21.2

    Release 21.2.2 and later allows customers to receive baggage data and purchase bags for itineraries where C type data has been filed by the carrier.

    C type baggage data is shopped and sold via the following:

    • C type baggage including max quantity and price information is viewable in the AirPrice and AirMerchandisingOfferAvailability responses.

    • C type baggage is sellable in the AirCreateReservation and AirMerchandisingFulfillment requests.

    While workflows should not change, it is important to ensure the @IsRepriceRequired element is not omitted from @OptionalServices in the AirCreateReservation and AirMerchandisingFulfillment requests because that information is used to ensure accurate pricing returns for the selected option.

    xPath:

    OptionalServices/OptionalService/@IsRepriceRequired

    • AirPriceRsp/AirPriceResult/AirPricingSolution/

    • AirMerchandisingOfferAvailabilityRsp/

    • AirCreateReservationReq/AirPricingSolution/

    • AirCreateReservationRsp/UniversalRecord/AirReservation/

    • AirMerchandisingFulfillmentReq/

    • AirMerchandisingFulfillmentRsp/UniversalRecord/AirReservation/

    Notes:

    • See DA 901 for further details and examples.

    Applies to

    If an optional service applies to a particular segment, that segment is defined in OptionalService/ServiceData @AirSegmentRef. If it applies to a particular passenger, the passenger is specified in OptionalService/ServiceData @BookingTravelerRef. A single OptionalService element can reference multiple air segments and passengers in the PNR.

    EMD

    Depending on the supplier, OptionalService/EMD displays additional information about the EMD, such as:

    • RefundReissueIndicator
    • Commissionable
    • FulfillmentType
    • Booking
    • DisplayCategory
    • AssociatedItem.

      • Notes:

      • The value P is not returned in the response at this time.
      • If an unsupported value is sent in @AssociatedItem, Universal API returns an error “Enum value 'Some Unsupported Value' not found".

    <air:OptionalService Type="PreReservedSeatAssignment" TotalPrice="EUR62.00" SupplierCode="KL" Available="true" PerTraveler="true" ServiceStatus="Offered"ProviderCode="MCH" BasePrice="EUR62.00ApproximateBasePrice="EUR0.00"" ApproximateTotalPrice="EUR0.00"OptionalServicesRuleRef="0T"SSRCode="RQST" AccessIndicator="MileageOrCurrency"ApplicableFFLevel="1" Private="false" FeeApplication="4 Per Traveler">

    <common:ServiceData AirSegmentRef="1T"/>

    <common:ServiceData BookingTravelerRef="2"/>

    <common:ServiceInfo>

    <common:Description>Economy Comfort</Description>

    <common:Description>PNR must be ticketed within 24 hours or seat will be cancelled</Description>

    </common:ServiceInfo>

    <common:Remark>KL 0345 - EUR80.00 PER PASSENGER Economy Comfort</Remark>

    <air:EMD RefundReissueIndicator="ReUse" Commissionable="false" FulfillmentType="Other than EMD" Booking="SSR"/>

    <air:AdditionalInfo Category="S7">ECONOMY COMFORT - MORE LEGROOM - MORE RECLINE - MORE COMFORT - DEDICATED AREA LOCATED AT THE FRONT OF ECONOMY CABIN</air:AdditionalInfo>

    <air:FeeApplication Code="4">Per Traveler</air:FeeApplication>

    </air:OptionalService>

    Bundled services

    OptionalService/BundledServices displays services bundled together.

    Rules

    Depending on the supplier, rules for the optional services may be returned in OptionalServices/OptionalServiceRules.

    Taxes

    OptionalService/TaxInfo is used to specify a tax breakdown with a category code, if a tax breakdown is provided by the carrier. A TaxInfo element is returned for each tax returned by the carrier. If more than one Tax is returned, the total of all taxes is returned in OptionalService @Taxes.

    Able to sell?

    When OptionalService @ViewableOnly="true", the optional services is viewable only and cannot be sold.

    An enhancement released with Universal API 21.4.2 stops returning services that cannot be sold. For example, an optional service that is ViewableOnly="true" is suppressed from the AirPrice and AMOA response.

    This is a limited release feature. Contact your Travelport representative for further details. Release 21.4

    Rich Content and Branding

    OptionalService/BrandingInfo adds Rich Content and Branding, including images.

  6. Other information may also be returned, such as traveler information, air segments, remarks, and host token.

    Information returned Description

    Traveler information

    • Specific travelers and segments applicable to a given Optional Service are indicated by the BookingTravelerRef and AirSegmentRef attributes.

      • These attribute values correspond to the AirSolution/SearchTraveler @Key and AirSegment @Key identified in the request within AirSolution.

    • If HostReservation was sent in the request, the response displays all travelers in the booking.

    • Any seat assignments in the booking are displayed within the appropriate SearchTraveler/Name.

    • If any loyalty cards were sent in the request or found in the booking, they are displayed within the appropriate SearchTraveler/Name.

    Air segments

    If HostReservation was sent in the request, the air segments of the carrier defined in HostReservation are displayed. If not,

    the air segments sent in the request are displayed in the response.

    Host token

    A /HostToken may be returned by some suppliers. This token must be used in a subsequent Seat Map request. The HostToken may have an associated expiration time.

    Remarks

    AirMerchandisingOfferAvailabilityRsp/Remark contains comments for the entire itinerary. The Remark element is returned with the text “Ancillary Services”.

    Note: At a lower level, Remarks can also be associated to individual Optional Services.

Errors and Warnings

Warning and error responses are typically returned in AirMerchandisingOfferAvailabilityRsp/ResponseMessage.

Code Error/Warning Reason for Message
3536

Multiple Universal Records present. All air segments must be in one Universal Record for Merchandising optional services to be returned.

The request is sent post-booking and multiple Universal Records exist.
4400

No Merchandising optional services returned for Flight(s) [Carrier Code] [Flight Number].

The request is sent and no optional service is returned for a carrier.

3512

The carrier reservation does not contain any valid flight segments.

The request:

  • Contains two AirSegments, one with a past date and another with an empty departure time, and does not contain @HostReservation.
  • Contains two AirSegments that both have an empty departure time and does not contain @HostReservation.
4402

No request for Merchandising optional services sent for Flight(s) ) [AY] [3126]. AirSegment Carrier, FlightNumber, DepartureTime and ArrivalTime are required.

Important! The warning will be similar to above, with the appropriate carrier and flight details.

The request contains two AirSegments, one with an empty departureTime and one that is active, and does not contain @HostReservation.

  • A successful response is returned for the active segments.
  • A warning is returned for the empty departure time.
3512

The carrier reservation does not contain any valid flight segments.

The request is sent with an open segment with no data and no @HostReservation.
3948

One or more air segments do not contain valid flight dates.

This message is returned in all schema versions. It can be an error or a warning. It occurs when an Air Merchandising Availability request is sent with invalid segments.

It is an error when the request:

  • Does not contain @HostReservation and all AirSegments have a past date.
  • Does not contain @HostReservation and no AirSegments have dates.

It is a warning when the request:

  • Contains one or more active AirSegments and one or more AirSegments that have past dates, and does not contain @HostReservation.

    • A successful response is returned for the active segments. A warning is returned for the past date segments.

  • Contains one or more active AirSegments and one or more AirSegments that do not have dates, and does not contain @HostReservation.
  • Contains three AirSegments, one with a past date, one with an empty departure time, and one that is active, and does not contain @HostReservation.

    • A successful response is returned for the active segment. Warnings are returned also:

    • One for the segment that has the past date: “One or more air segments do not contain valid flight dates.”
    • One for the empty departure time, similar to: “No request for Merchandising optional services sent for Flight(s) ) [Carrier Code] [Flight Number]. AirSegment Carrier, FlightNumber, DepartureTime and ArrivalTime are required."
 

No warning is returned by Universal API.

Rather, Optional Services are not included in the response for any ineligible segments. However, warnings directly from the supplier may be returned in the response.

The request is sent and some air segments in a request are ineligible for optional services, but other segments are successful.

 

Review specifics for Offer Availability:

Use the Air Merchandising Seat Map request to obtain specific seat assignments associated with the selected seating options.

Use the Air Merchandising Fulfillment request to book the Optional Services.