Air Merchandising Fulfillment for ATPCO Carriers
The Air Merchandising Fulfillment request for ATPCO carriers, such as KL, can include optional services for multiple carriers and multiple providers. The request is made post-booking and the response returns the confirmed optional services.
Each Optional Service that is submitted should be a different type. For example, users should not send two OptionalService elements for "checked 1st bag". Additionally, the same service ("checked 1st bag") cannot be sent with Quantity="2" (or more) or an error is returned.
Note: Universal API only supports OptionalService @Quantity="1" for ATPCO-filed optional services.
Schema
Located in AirReqRsp.xsd:
Request
Air Merchandising Fulfillment for ATPCO carriers follows the general Air Merchandising Fulfillment process. Additionally:
- The following data is required:
- OptionalService @PerTraveler set to "true" because the carriers return seats per passenger.
- A separate EMD (Electronic Miscellaneous Document) for payment of paid seats. (The CreditCard element is not used.)
- OptionalService/ServiceData/Description. Without Description, the ASVC SSR will not be created.
- OptionalService attributes:
- ServiceSubCode="0AA"
- Remark:[Commercial Name]
- OptionalService attributes:
- SSRCode="XBAG"
- IssuanceReason="C"
-
OptionalService @ServiceSubCode is required if OptionalService @Type="PreReservedSeatAssignment".
If @Type is "PreReservedSeatAssignment" and @ServiceSubCode is missing from:
- All OptionalService elements, an error is returned and no services are fulfilled: OptionalService PreReservedSeatAssignment is missing ServiceSubCode.
- Some OptionalService elements, Optional Services that include @ServiceSubCode are fulfilled, and a warning is returned for those that do not: OptionalService PreReservedSeatAssignment is missing ServiceSubCode.
- For the Galileo (1G) and Apollo (1V) providers, Universal API retrieves/imports the PNR from the provider. Then, Universal API extracts the PTC from BookingTraveler/NameRemark @RemarkData for the current PNR and sends that PTC in the request. If a PTC cannot be extracted, Universal API checks BookingTraveler/TravelerType to determine the PTC to send in the request. If a PTC is still not found, Universal API sends an adult (ADT) PTC in the request.
- For the Worldspan (1P) providers, Universal API retrieves/imports the PNR from the provider and populates BookingTraveler/TravelerType with the PTC, which is sent in the reques. Age, if available, is also sent in the request.
-
Use @SecondaryType to request secondary optional services. See ATPCO Secondary Optional Services.
Therefore, the following data from the Air Merchandising Offer Availability or Seat Map response must be included in any subsequent Merchandising Fulfillment request:
If the following data is returned in the Air Merchandising Offer Availability or Seat Map response, it must be included in any subsequent Merchandising Fulfillment request:
Note that the values associated with this data are examples and may be subject to changes in the ATPCO filing by the carrier.
Important! These values should NOT be hard-coded into a client application. However, the returned Air Merchandising Offer Availability or Seat Map response values should always be included in the subsequent Fulfillment request.
If an Optional Service that references an infant (INF PTC) is sent in a request, it is ignored and a warning is returned: "OptionalServices may not be Supported/Required for passenger type INF."
Note: This warning is returned as an error if Seat Map is requested for INF PTC only.
If the request included an Optional Service that references a Booking Traveler Passenger Type Code (PTC) that includes an age, Universal API converts the PTC with age to an applicable three-alpha-character PTC and saves the Optional Service in the Universal Record (UR). For example, if the PTC is C08, uAPI convers to PTC CNN. CNN is saved in the UR.
Important! Do not use OptionalService for standard seats. Use SpecificSeatAssignment.
Response
The AirMerchandisingFulfillmentRsp contains the entire Universal Record including new or updated Optional Service information.
The ATPCO-filed Optional Service is saved in the Universal Record with an "Offered" status, if the ASVC SSR is in pending status (i.e., the airline has not yet confirmed the sale of the Optional Service). The ServiceStatus is updated when the airline confirms the sale of the Optional Service and the Universal Record is retrieved or synchronized. When an EMD is issued, the OptionalService @ServiceStatus is updated in the Universal Record with "Fulfilled".
The following table list the SSR Status Code that updates the OptionalService @ServiceStatus in the Universal Record when the Universal Record is retrieved or synchronized.
Provider |
ASVC SSR Status Code |
OptionalService @ServiceStatus |
---|---|---|
1G, 1V, 1P |
HK |
Confirmed |
1G, 1V, 1P |
KK |
Confirmed |
1G, 1V, 1P |
KD |
Confirmed |
1G, 1V, 1P |
UN |
Pending |
1G, 1V, 1P |
UC |
Pending |
1G, 1V, 1P |
HX |
Cancelled |
1G, 1V, 1P |
XX |
Cancelled |
1P |
NO |
Cancelled |
1G, 1V, 1P |
HI |
Fulfilled |
1G, 1V, 1P |
Other |
Offered |
If the Optional Service @Type=PreReservedSeatAssignment or there is a SpecificSeatAssignment, a chargeable seat characteristic is set on the provider, regardless if the seat is added for the first time or modified (any of the modify scenarios; standard to standard, standard to paid, paid to standard, etc.). Passenger and segment information, Loyalty Card priority (if available), and Fare Information (if available) are sent in the Air Merchandising Fulfillment request. The prices that are returned are based on the information sent, and can differ based on the passenger. If the Optional Service is not PreReservedSeatAssignment, Universal API does not recheck the price and assumes data sent in the request is correct.
If the Optional Services in the fulfillment request are a mix of paid seat and non-paid seat Optional Services, Universal API attempts to fulfill all services. However, Universal API will fulfill the non-paid seat Optional Service even if there is a price or availability change on the paid seat.
Fulfillment of Optional Services
To transmit fulfillment information, Universal API internally creates an ASVC SSR, which is sent to the carrier. This data is tied to the segment per booking traveler and the Optional Service; each traveler and Optional Service pair has a corresponding ASVC SSR if payment was required for the Optional Service.
Each optional service is uniquely identified by the ASVC SSR at the Service Data level, based a comparison of each ASVC SSR inside the booking traveler with the Optional Service data. The BookingTravelerRef, AirSegmentRef, Carrier, IssuanceCode (RFIC), and ServiceSubCode of each ASVC SSR must match the Optional Service data. If the RFIC code does not exist in the ASVC SSR, it is ignored by the mapping logic of the ASVC SSR with the Optional Service. The ServiceSubCode is taken from parsing FreeText in the ASVC SSR and is the value between first and second "/" in the ASVC SSR FreeText.
There is a possibility that the same Optional Service is sold more than once, at the same time, e.g., a meal Optional Service is specified in AirMerchandisingFulfillmentReq twice instead of specifying the quantity as two. In this scenario, the ASVC SSR is mapped with the first matching Optional Service. The next matching ASVC SSR is mapped with the other optional service.
The ASVC SSR reference is saved in OptionalService/ServiceData in the Universal Record. When the Universal Record is retrieved, the ASVC SSR and Optional Service association are synchronized with the provider data. After the ASVC SSR is associated with an Optional Service the association remains until the ASVC SSR is deleted.
The ASVC SSR is returned in the Air Merchandising Fulfillment response in UniversalRecord/BookingTraveler:
<BookingTraveler Key="gKKYlP5/Rh+dNz9K0S/aAQ==" TravelerType="ADT" Age="34" DOB="1978-01-29" Gender="M">
<BookingTravelerName First="Venki" Last="test"/>
<SSR Key="KAJ0hqT7TZyiymTVKTLBgA==" SegmentRef="216DLEkCRCiwyK9qwlVdFA==" Status="HI" Type="ASVC" FreeText="**A/0B5/SEAT/ECONOMY COMFORT/A/0555110001610C1 " Carrier="KL" ProviderReservationInfoRef="597034" ElStat="A"/>
</BookingTraveler>
In the above example:
- The "HI" status means that an EMD is issued for the Optional Service.
- The FreeText value, "**A/0B5/SEAT/ECONOMY COMFORT/A", breaks down to:
- IssuanceReason = "A"
- ServiceSubCode = "0B5"
- SSRCode = "Seat"
- Facility Remark = "Economy Comfort"
- The type of EMD = "A""or "S"
- 0555110001610 is the EMD number followed by C which indicates Coupon number 1
After the correct ASVC SSR is identified for the optional service, the ASVC SSR reference is included in OptionalService/ServiceData, with the Booking TravelerRef:
<common_v50_0:ServiceData BookingTravelerRef="gKKYlP5/Rh+dNz9K0S/aAQ==" AirSegmentRef="216DLEkCRCiwyK9qwlVdFA==" TravelerType="ADT" >
<SsrRef Key="KAJ0hqT7TZyiymTVKTLBgA==" />
</ServiceData>
Show SSR and ASVC SSR creation details and flowAn airline can file an Optional Service with ATPCO as an ASVC-only SSR service or as a dual-SSR service.
When the airline files the Optional Service with the SSR code ASVC, it is considered an ASVC-only SSR service. The ASVC SSR is created for each optional service sent in the Air Merchandising Fulfillment request (AirMerchandisingFulfillmentReq) and Air Booking request (AirCreateReservationReq).
Note: The ASVC SSR is not created for Air Bookings on Worldspan.
When the airline files the optional service with an SSR code that is not ASVC, it is considered a dual-SSR service. The SSR code can be:
- A standard, industry-defined SSR code, for example XBAG.
- A non-standard, airline-defined SSR code, for example BAGA.
Two SSRs are created for each optional service sent in the Air Merchandising Fulfillment request and the Air Booking request: one for the SSR code filed by the airline and one for the ASVC SSR. For example, carrier XX files a bag Optional Service with SSR Code “XBAG”. Dual SSRs are created: XBAG SSR and ASVC SSR.
Note: Dual SSRs are not created for Air Bookings on Worldspan.
Some SSRs require free text that must be sent in the request in OptionalService @SSRFreeText. If the free text is not sent, an error is returned:
Some SSRs do not allow free text. If the free text is sent for an SSR that does not allow free text, an error is returned:
The SSR and the ASVC SSR are saved in the Universal Record (UR).
Note: If the provider does not support the SSR sent in the request, the error sent by the provider system is returned in the Universal API response and the user must remove the Optional Service and delete the SSR before resending.
In the Merchandising Fulfillment response, the confirmed Optional Service is returned in an SSR element for each traveler per segment. For example:
<SSR Key="365677" SegmentRef="477783" Status="KD" Type="ASVC" FreeText="**A/0B5/SEAT/ECONOMY COMFORT/A" Carrier="KL" ProviderReservationInfoRef="597034"/>
In this example:
- The "KD" status means that an EMD must be issued to pay for the Optional Service.
- The FreeText value, "**A/0B5/SEAT/ECONOMY COMFORT/A", breaks down to:
- IssuanceReason = "A"
- ServiceSubCode = "0B5"
- SSRCode = "Seat"
- Facility Remark = "Economy Comfort"
- The type of EMD = "A" or "S"
Typically, Universal API receives the ASVC SSR from the carrier before returning the Merchandising Fulfillment response. However, if the SSR has not yet been received, then the Merchandising Fulfillment response still has the ASVC request data. Therefore, if the Status of the SSR is returned as "PN" (Pending Need), the ASVC response is not yet returned. A subsequent retrieval shows the updated "KD" status if an EMD must be issued to pay for the Optional Service. An ASVC SSR with status code "KK" means that an EMD does not need to be issued.
Fulfillment of optional services is done via EMD (Electronic Miscellaneous Document).
After the Merchandising Fulfillment response is returned, SSR data can be used to create an EMD to submit payment information to the carrier. The carrier will also send a message with the last date the EMD must be issued by. If the EMD is not issued by the specified date, the carrier will cancel the Optional Service.
Exceptions
AirMerchandisingFulfillment will fail if OptionalService with Type="PreReservedSeatAssignment" is sent with a bulkhead seat and no Infant is traveling with the Adult.
EK will confirm a different seat if the seat that has been requested is not available.
Review specifics for Air Merchandising Fulfillment:
Optional Services may be canceled or modified, depending on the supplier and type of change.