EN
Sign In
Developers > Flight > Reference >ancillary-query-service

Flight Ancillary API Reference (v1.29)

Download OpenAPI specification:Download

API Support: gnjpcxjk@trip.com URL: https://trip.com Terms of Service

You can use this service to help your customers who book flight tickets on your platform or other platforms to purchase available ancillary products for their flights.

How to use this service:

  1. If the customer wants to purchase additional baggage allowance, you can use the QueryAncillaryList API to help search for available additional baggage allowance products for the customer's flight;
  2. After the customer has selected the product that they want, you can use the QueryAncillaryDetail API to get the details of the selected product.

This documentation contains the following sections: introduction, glossary, API overview, access to API, error codes, release history, getting started, FAQs, and technical support.

Introduction

Discover what’s possible with the available ancillary product search service for distributors!

Before using, you need to understand the interaction of API, including the way of authorization, exception handling, and environment. Please refer to the [API Guides](Flights Web API Guide (trip.com)).

Data about sensitive information such as ID and cell phone numbers will be encrypted. If decryption is needed, please ask for decryption permission when accessing.

Three important questions will be elaborated on below to help you better use this service.

1. What are Ancillary Products?

Ancillary products are a general term for products other than the air ticket purchased by customers. They can be bought together with, after or without the air ticket.

2. Supported Ancillary Products

Supported ancillary products include additional baggage allowance, seat selection, and online check-in.

Ancillary products are distinguished by the field ProductType.

Code Type of Ancillary Product
CheckedBag additional baggage allowance
Seat seat selection
CheckIn online check-in
CFAR CancelForAnyReason
AirHelp AirHelp
FTG Flight Ticket Guarantee
TravixPackage TravixPackage
RentalCar RentalCar
SGR SGR
CalamityFee CalamityFee
Insurance Insurance
TravixRP Travix RefundProtect
CarryOnBag CarryOn baggage
STP Self-Transfer Protect

3. What to Expect from this Service?

This service offers functions including

  • search for available ancillary products for a customer's flight;

  • get the details of the product selected by a customer.

Glossary

For your convenience, we have listed some phrases that may be unfamiliar to you, as follows:

Glossary
Description
 Example
ProductType supported ancillary products additional baggage allowance

API Overview

API Name Description
AncillaryListSearch It is used to search for available ancillary product resources.
AncillaryDetailSearch It is used to get the details of a selected ancillary product by its token that you can get from the response of the QueryAncillaryList API.
SeatMapResult It is used to retrieve the seat map for a certain flight/offer.
AncillaryProductPurchaseCheck The purpose of the AncillaryProductPurchaseCheck API is to validate the ancillary products that the user has selected.

Access to the API

Access is available at the following URLs.

Environment Base URL for HTTP Endpoints
Production https://apiproxy.ctrip.com/apiproxy/flight/ancillaryqueryservice/{interfaceName}
Test https://apiproxy-fws.ctripqa.com/apiproxy/flight/ancillaryqueryservice/{interfaceName}

Error Codes

An Error field appearing in the response means the API call has failed. Code in Error indicates the error code, and Message indicates the specific information of the error.

Please refer to the [API Guides](Flights Web API Guide (trip.com)) for error codes.

Special Error Codes

The following table only lists special error codes related to the business logic of the API . For other error codes, see Common Error Codes.

Common Error Codes

Please refer to the API Guides for common error codes.

Release History

We recommend that you begin deployment of each update promptly to gain access to new features experiences, and integrated security as soon as possible.

Minor versions for the API to control small changes history as following table:

Version Release Date API Methods Update Notes
v1.0 2023-04-03 AncillaryListSearch , AncillaryDetailSearch , SeatMapResult The newly added APIs include AncillaryListSearch , AncillaryDetailSearch and SeatMapResult.
v1.1 2023-04-23 AncillaryDetailSearch，AncillaryListSearch Adjust the query example, Adjust service URL and baggage allowance query parameters.
v1.6 2023-05-09 AncillaryDetailSearch，AncillaryListSearch CFAR contract
v1.8 2023-06-01 SeatMapResult, AncillaryListSearch Update contract, "ErrorDetails" in AncillaryListSearch, "PTC" in SeatMapResult
v1.9 2023-06-20 AncillaryListSearch , AncillaryDetailSearch Update baggage contract, "BaggageSpecification" in AncillaryListSearch and AncillaryDetailSearch
v1.10 2023-07-10 AncillaryListSearch , AncillaryDetailSearch , SeatMapResult Update baggage contract, Seat contract
v1.11 2023-09-21 AncillaryListSearch Add "contentType" in AncillaryListSearch
v1.12 2023-10-24 AncillaryListSearch Update AirHelp and FTG contract
v1.13 2023-11-15 AncillaryListSearch Update TravixPackage contract
v1.14 2023-11-23 AncillaryListSearch Update ErrorDetail contract
v1.19 2024-01-05 AncillaryListSearch Add "RentalCarSpecific" to AncillaryListSearch. Add RentalCar, SGR and CalamityFee as new product type
v1.20 2024-02-02 AncillaryListSearch Add "InsuranceSpecific" to AncillaryListSearch. Add Insurance as new product type
v1.21 2024-04-19 AncillaryListSearch Add "DistBookingCheckInfo" to AncillaryListSearch.
v1.22 2024-06-05 AncillaryListSearch Update carryOn baggage
v1.23 2024-08-15 AncillaryListSearch Add "TravixAffiliateCode" "TravixChannel" to AncillaryListSearch
v1.24 2024-09-24 AncillaryListSearch Update STP
v1.25 2024-10-12 AncillaryProductPurchaseCheck Add AncillaryProductPurchaseCheck API
v1.26 2024-10-25 AncillaryListSearch,SeatMapResult Add "AncillaryResourceType" to AncillaryListSearch, Add "TravixAffiliateCode" "TravixChannel" "AncillaryResourceType" to SeatMapResult
v1.27 2025-01-22 AncillaryListSearch, AncillaryProductPurchaseCheck, SeatMapResult Add "FlightBookingPrice" to CFARSpecific in AncillaryListSearch. Add UID, ValidationScene, TravixAffiliateCode, TravixChannel, AncillaryResourceType to AncillaryProductPurchaseCheck interface. Add FlightGroupSpecific to SeatMapResult interface. Add AID, SID to FlightGroupSpecific. Add Nationality to IdentityDoc. Add OriginalSettlePriceDetailInfos to PriceInfo
v1.28 2025-02-06 SeatMapResult Add "Result" to ResponseBody in SeatMapResult API
v1.29 2025-02-13 AncillaryListSearch Add "EntryPoint" to Request and add "Contents" to Response

Service

Provides the resource query function of air ticket supplementary products.

AncillaryDetailSearch

Missing description for operation,fill in here

Request Body schema: application/json

Missing description, fill in here.

required
object (AncillaryDetailSearchRequestBody)
required
Array of objects (QueryInfo) non-empty [ items ]

The products that you want to query for their details

Array (non-empty)
Token
required
string

The token of the ancillary product

required
object (RequestHeaderType)
Culture
required
string

Use the culture parameter to specify a culture for your request. The default is zh-cn

CurrencyCode
required
string

Use the currency code parameter to specify a currency for your request. The default is CNY

TransactionID
required
string

The UUID used to track the Trace/transaction

Responses

Request samples

Content type
application/json

success request

Loading...

Response samples

Content type
application/json

success response

Loading...

AncillaryListSearch

Missing description for operation,fill in here

Request Body schema: application/json

Missing description, fill in here.

required
object (AncillaryListSearchRequestBody)
AffiliateCode
required
string

The supplier code for insurance and RP.

AncillaryResourceType
required
string

AncillaryResourceType to be queried,E.g. TripContent, TravixContent

Channel
required
string

The channel defined by Trip.com, usually working with the subchannel. Please contact your product and business contract for this content

required
object (DeviceInfo)
DeviceID
required
string

DeviceID is a unique identifier for a device that is used to track usage, identify device type and version, and manage access permissions.

DeviceType
required
string

Device type - possible values: "desktop", "tablet", "mobile", "server"

required
object (Platform)
BrowserName
required
string

Browser Name - required only when Browser Type is "other_browser"

BrowserType
required
string

Browser Type - possible values: "chrome", "firefox", "internet_explorer", "edge", "opera", "safari", "other_browser"

BrowserVersion
required
string

Browser Version

OperatingSystemName
required
string

Operating System Name - required only when Operating System Type is "other_os"

OperatingSystemType
required
string

Operating System Type - possible values: "mac_os", "chrome_os", "i_os", "android", "windows", "linux", "other_os"

OperatingSystemVersion
required
string

Operating System Version

PlatformType
required
string

Platform Type - possible values: "app", "web"

required
object (PaxInfo)
required
Array of objects (IdentityDoc) non-empty [ items ]

Identity document details

Array (non-empty)
Age
required
integer <int32>

Age

Birthday
required
string

The date of birth of the passenger, format: yyyy-MM-dd HH:mm:ss

ExpiryDate
required
string

The datetime when the identity document expires, format:yyyy-MM-dd HH:mm:ss

Gender
required
string

Gender of the passenger, M means male; F means female

ID
required
string

Uniquely identifies the document from all other identity documents issued by the state or organization. e.g. passport number, drivers license number

Nationality
required
string

Passenger nationality

PTC
required
string

Passenger type code. Use PTC to define the identification requirements and age range for a particular passenger type: ADT (Adult), CHD(Child), INF(Infant). A required field

PaxName
required
string

Passenger name

Residency
required
string

Residency refers to the legal status of living in a particular place.

ResidentStateCode
required
string

Optional. Residential state code. ex. WA for Washington.

TicketService
required
boolean

Only for Hepstar insurance. Whether use Hepstar ticket service.

Type
required
integer <int32>

Identity document types, 1: ID card; 2: Passport; 3: Student card; 4: Military ID card; 6: Driver's license; 7: Mainland Travel Permit for Hong Kong and Macao Residents; 8: Mainland Travel Permit for Taiwan Residents; 10: Exit-Entry Permit for Travelling to and from Hong Kong and Macao; 11: Seaman's book; 20: People's Republic of China Foreigner's Permanent Residence Identity Card; 21: People's Republic of China Travel Document; 22: Exit-Entry Permit for Travelling to and from Taiwan; 23: Chinese People's Liberation Army soldier card; 24: Temporary ID card; 25: Household register; 26:Police officer certificate

ProductTypes
required
Array of strings non-empty

The types of ancillary products that you have requested; you can input more than one values in single request. E.g.Checkedbaggage , CabinBaggage

SaleMethod
required
string

Sale methods: Standalone (book ancillary products only without flights); InFlow (book ancillary products together with flights); PostBooking (book ancillary products after flights have been booked)

required
object (SearchCriteria)
required
object (ExtraRequestInfo)
required
object (BaggageSpecific)
PriceMarkup
number <decimal>

Markup for Gordian, used to transmit and calculate profits.

ServiceSources
required
Array of strings non-empty

Baggage resource provider to be queried

required
object (CFARSpecific)
required
Array of objects (Ancillary) non-empty [ items ]

Ancillaries selected by the user, which can be supported by CFAR

EntryPoint
required
string

EntryPoint

FlightBookingPrice
required
number <decimal>

Flight booking price with tax and Travix booking fee and surcharge.

PurchaseOptionID
required
string

During a Shopping/Offering request, multiple optional price points may be returned, and each price point corresponds to a PurchaseOptionID. Therefore, when making a Pricing request, the user's selected PurchaseOptionID must be specified.

SearchType
required
string

For Trip to recognise this request is Shopping or Pricing - possible values: "Shopping"，"Pricing"

SupplierSessionID
required
string

SupplierSessionID is empty during the first Shopping/Offering request, and the SupplierSessionID is only created once on Hopper. It is required if it is a Pricing request, Shopping re-query request or SupplierSessionID is existed

required
object (InsuranceSpecific)
SessionID
required
string

SessionId will be unique identifier for a single booking.

SourceType
required
string

SourceType corresponds to device/platform info. It could be desktop | web | mobile.

TotalBookingPrice
required
number <decimal>

Total booking price for insurance.

Traffic
required
string

Traffic corresponds to Travix channel type. It could be meta | direct | kayakin etc..

required
object (RefundProtectSpecific)
SessionID
required
string

SessionId will be unique identifier for a single booking.

SourceType
required
string

SourceType corresponds to device/platform info. It could be desktop | web | mobile.

TotalBookingPrice
required
number <decimal>

Total booking price for Travix RP.

Traffic
required
string

Traffic corresponds to Travix channel type. It could be meta | direct | kayakin etc..

required
object (RentalCarSpecific)
CarDailyPrice
required
number <decimal>

Daily cost to rent a car

EndDateTime
required
string

Time to return a car. It is based on local time. Time format: yyyy-MM-dd HH:mm:ss

InsurancePrice
required
number <decimal>

Insurance price

PickUpLocation
required
string

Place to pick up the rental car

ProductName
required
string

Product name

ReturnLocation
required
string

Place to return the rental car

StartDateTime
required
string

Start time to rent a car. It is based on local time. Time format: yyyy-MM-dd HH:mm:ss

SupplierBookPayload
required
string

SupplierBookPayload is a fulfillment relevant info which is used for exchange team.

required
object (SeatSpecific)
PriceMarkup
number <decimal>

Markup for Gordian, used to transmit and calculate profits.

SerialNos
required
Array of strings non-empty

The serial number for seat selection, used to retrieve seat availability results or aircraft seat maps

ServiceSources
required
Array of strings non-empty

Seat resource provider to be queried

required
object (TravixPackageSpecific)
required
Array of objects (TravixPackageContentType) non-empty [ items ]

The package information obtained from the InRule system

required
object (FlightGroupSpecific)
AID
required
string

The flight AID, will be used if SpecificType = ResponseToken

required
Array of objects (FlightProductGroupInfo) non-empty [ items ]

Fare info

Array (non-empty)
required
object (DistBookingCheckInfo)
GroupIndex
required
integer <int32>

The fare index, used to distinguish among different fares

required
Array of objects (TransportInfo) non-empty [ items ]

Itinerary information

OfferToken
required
string

The flight search token, a required field if SpecificType = ResponseToken

OrderID
required
integer <int64>

The order ID, a required field if SpecificType = FlightOrder

required
Array of objects (ProductDetail) non-empty [ items ]

Product details

SearchCriteriaToken
required
string

The flight search token , a required field if SpecificType = ResponseToken

SpecificType
required
string

Specify how the API gets flight info. Following options are provided: 1. TransportSpecific: input the flight info into the ItineraryInfo node, generally used when SaleMethod = Standalone (book ancillary products only without flights); 2. FlightOrder: the API will get the flight info through the order ID from the OrderID field, generally used when SaleMethod = PostBooking (book ancillary products after flights have been booked); 3. ResponseToken: the API will get the flight info through the flight token from the SearchCriteriaToken, OfferToken fields, generally used when SaleMethod = InFlow (book ancillary products together with flights)

SID
required
string

The flight SID, will be used if SpecificType = ResponseToken

TripType
required
string

Trip types, please use the following values: OW(one-way trip), RT(round trip), MT(multi-city trip)

SubChannel
required
string

The subchannel defined by Trip.com, working with the channel. Please contact your product and business contract for this content

TravixAffiliateCode
required
string

Travix Alliance Code

TravixChannel
required
string

Travix Channel

required
object (RequestHeaderType)
Culture
required
string

Use the culture parameter to specify a culture for your request. The default is zh-cn

CurrencyCode
required
string

Use the currency code parameter to specify a currency for your request. The default is CNY

TransactionID
required
string

The UUID used to track the Trace/transaction

Responses

Request samples

Content type
application/json
Example

success response

Loading...

Response samples

Content type
application/json
Example

CheckedBag success response

Loading...

AncillaryProductPurchaseCheck

Missing description for operation,fill in here

Request Body schema: application/json

Missing description, fill in here.

required
object (AncillaryProductPurchaseCheckRequestBody)
AncillaryResourceType
required
string

AncillaryResourceType to be queried,E.g. TripContent, TravixContent

Channel
required
string

The channel defined by Trip.com, usually working with the subchannel. Please contact your product and business contract for this content

required
object (AncillaryProductCheckFlightProductInfoType)
required
Array of objects (AncillaryProductCheckTransportInfoType) non-empty [ items ]

Itinerary information

Array (non-empty)
required
object (AncillaryProductCheckFlightInfoType)
required
Array of objects (AncillaryProductCheckProductDetailType) non-empty [ items ]

Product details

Array (non-empty)
BookingChannel
required
string

Flight price resources. A required field

ProductDetailRefID
required
integer <int32>

The index of the ProductDetailList node

ValidatingCarrierCode
required
string

IATA two-letter code of the validating carrier, such as MU for China Eastern Airlines. A required field

required
Array of objects (AncillaryProductCheckPaxInfoType) non-empty [ items ]

Passenger info

Array (non-empty)
Birthday
required
string

The date of birth of the passenger, format: yyyy-MM-dd. A required field

PTC
required
string

Passenger type code. Use PTC to define the identification requirements and age range for a particular passenger type: ADT (Adult), CHD(Child), INF(Infant). A required field

PaxName
required
string

Passenger name. A required field

PaxRefID
required
integer <int32>

The index of the PaxList node

SaleMethod
required
string

Sale methods: Standalone (book ancillary products only without flights); InFlow (book ancillary products together with flights); PostBooking (book ancillary products after flights have been booked)

SubChannel
required
string

The subchannel defined by Trip.com, working with the channel. Please contact your product and business contract for this content

TravixAffiliateCode
required
string

Travix Alliance Code

TravixChannel
required
string

Travix Channel

UID
required
string

User ID

ValidationScene
required
string

Validation Scene. Enum: CreateOrder/ModifyOrder/SelectSeat

required
object (AncillaryProductCheckXPurchasedInfoType)
required
Array of objects (AncillaryProductCheckXPurchasedDetailType) non-empty [ items ]

Missing description, fill in here.

Array (non-empty)
required
object (AncillaryProductCheckXProductInfoType)
required
Array of objects (AncillaryProductCheckXPurchasedRefDetailType) non-empty [ items ]

Associated purchased information for ancillary product.

required
object (RequestHeaderType)
Culture
required
string

Use the culture parameter to specify a culture for your request. The default is zh-cn

CurrencyCode
required
string

Use the currency code parameter to specify a currency for your request. The default is CNY

TransactionID
required
string

The UUID used to track the Trace/transaction

Responses

Request samples

Content type
application/json

success request

Loading...

Response samples

Content type
application/json

AncillaryProductPurchaseCheck success response

Loading...

SeatMapResultAsync

Missing description for operation,fill in here

Request Body schema: application/json

Missing description, fill in here.

required
object (SeatMapResultRequestBody)
AncillaryResourceType
required
string

AncillaryResourceType to be queried,E.g. TripContent, TravixContent

Channel
required
string

The channel defined by Trip.com, usually working with the subchannel. Please contact your product and business contract for this content

required
object (FlightGroupSpecific)
AID
required
string

The flight AID, will be used if SpecificType = ResponseToken

required
Array of objects (FlightProductGroupInfo) non-empty [ items ]

Fare info

Array (non-empty)
required
object (DistBookingCheckInfo)
GroupIndex
required
integer <int32>

The fare index, used to distinguish among different fares

required
Array of objects (TransportInfo) non-empty [ items ]

Itinerary information

OfferToken
required
string

The flight search token, a required field if SpecificType = ResponseToken

OrderID
required
integer <int64>

The order ID, a required field if SpecificType = FlightOrder

required
Array of objects (ProductDetail) non-empty [ items ]

Product details

SearchCriteriaToken
required
string

The flight search token , a required field if SpecificType = ResponseToken

SpecificType
required
string

Specify how the API gets flight info. Following options are provided: 1. TransportSpecific: input the flight info into the ItineraryInfo node, generally used when SaleMethod = Standalone (book ancillary products only without flights); 2. FlightOrder: the API will get the flight info through the order ID from the OrderID field, generally used when SaleMethod = PostBooking (book ancillary products after flights have been booked); 3. ResponseToken: the API will get the flight info through the flight token from the SearchCriteriaToken, OfferToken fields, generally used when SaleMethod = InFlow (book ancillary products together with flights)

SID
required
string

The flight SID, will be used if SpecificType = ResponseToken

TripType
required
string

Trip types, please use the following values: OW(one-way trip), RT(round trip), MT(multi-city trip)

required
object (PaxInfo)
required
Array of objects (IdentityDoc) non-empty [ items ]

Identity document details

Array (non-empty)
Age
required
integer <int32>

Age

Birthday
required
string

The date of birth of the passenger, format: yyyy-MM-dd HH:mm:ss

ExpiryDate
required
string

The datetime when the identity document expires, format:yyyy-MM-dd HH:mm:ss

Gender
required
string

Gender of the passenger, M means male; F means female

ID
required
string

Uniquely identifies the document from all other identity documents issued by the state or organization. e.g. passport number, drivers license number

Nationality
required
string

Passenger nationality

PTC
required
string

Passenger type code. Use PTC to define the identification requirements and age range for a particular passenger type: ADT (Adult), CHD(Child), INF(Infant). A required field

PaxName
required
string

Passenger name

Residency
required
string

Residency refers to the legal status of living in a particular place.

ResidentStateCode
required
string

Optional. Residential state code. ex. WA for Washington.

TicketService
required
boolean

Only for Hepstar insurance. Whether use Hepstar ticket service.

Type
required
integer <int32>

Identity document types, 1: ID card; 2: Passport; 3: Student card; 4: Military ID card; 6: Driver's license; 7: Mainland Travel Permit for Hong Kong and Macao Residents; 8: Mainland Travel Permit for Taiwan Residents; 10: Exit-Entry Permit for Travelling to and from Hong Kong and Macao; 11: Seaman's book; 20: People's Republic of China Foreigner's Permanent Residence Identity Card; 21: People's Republic of China Travel Document; 22: Exit-Entry Permit for Travelling to and from Taiwan; 23: Chinese People's Liberation Army soldier card; 24: Temporary ID card; 25: Household register; 26:Police officer certificate

SaleMethod
required
string

Sale methods: Standalone (book ancillary products only without flights); InFlow (book ancillary products together with flights); PostBooking (book ancillary products after flights have been booked)

SerialNo
required
string

The serial number for seat selection, used to retrieve seat availability results or aircraft seat maps

SubChannel
required
string

The subchannel defined by Trip.com, working with the channel. Please contact your product and business contract for this content

TravixAffiliateCode
required
string

Travix Alliance Code

TravixChannel
required
string

Travix Channel

required
object (RequestHeaderType)
Culture
required
string

Use the culture parameter to specify a culture for your request. The default is zh-cn

CurrencyCode
required
string

Use the currency code parameter to specify a currency for your request. The default is CNY

TransactionID
required
string

The UUID used to track the Trace/transaction

Responses

Request samples

Content type
application/json

success request

Loading...

Response samples

Content type
application/json

success response

Loading...

FAQs

  1. Q:Why the Flight Quote unavailable for us?

    Make sure the channel of your requested was approved.

  2. Q:Why is the quoted price higher than others?

    Different sales channels, affected by the pricing strategy, may have different quotations.

If you don't find the answer that you are looking for in the FAQ section, please provide us with necessary information such as the time of calling an API, what you want to do with the API, the request and response message, the access path and environment. We will get back to you as soon as possible.