DerbySoft GDN Seller API

TABLE OF CONTENTS

Request Payload Example

Request Payload Structure
Response

It’s the endpoint responsible for flight search.

Version	Date	Description of Edit
Beta	2025/09/16	Initial Commit
V1.0	2025/10/22	AirShoppingRQ: Modified promotionCriteria data structure to support multi-supplier search scenarios AirShoppingRS: Modified Price object Add SSRs node to support returning optional paid ancillary services Add technicalCapabilities
V1.1	2026/07/02	AirShoppingRS: Added totalWeightMeasure to support total baggage weight allowance.
V2.0	2026/08/15	Supported return POO currency and settlement currency Added taxCode in price breakdown. Added journey price splitting (onwardTrip.price, returnTrip.price). Added legInfos[] for stopovers (sequence, airport, duration, equipment). Supported leg-level carbon_emissions in leg properties. Added promotionDetailInfo under offer totalPrice and passenger fare price to return the promotion code, original base amount, discount amount, and currency.

Request Details
Path	V1.0	/api/flight/connectivity/search/airShopping
Path	V1.0	/api/flight/connectivity/search/V1.1/airShopping
Path	V2.0	/api/flight/connectivity/search/V2.0/airShopping

TRequest Payload Example

{
   "flightRequests": [
       {
           "cabinClass": "4",
           "currency": "USD",
           "arrivalInfo": {
               "iataLocationCode": "SIN",
               "type": "airportcode"
           },
           "departureInfo": {
               "iataLocationCode": "BKK",
               "departureDate": "2026-10-24",
               "type": "airportcode"
           }
       }
   ],
   "flightCriteria": {
       "flightType": 2
   },
   "carrierCriterias": [
       {
           "supplierName": "",
           "airlineCode": "",
           "agencyCode": "PKAIR-AGENCY"
       }
   ],
   "promotionCriterias": [
       {
           "supplierName": "",
           "promotionCode": "",
           "airlineCode": "",
           "agencyCode": "PKAIR-AGENCY"
       }
   ],
   "paxList": [
       {
           "paxType": "ADT",
           "count": 2
       }
   ]
}

Request Payload Structure

Key	Parent	Type	Mandatory/Optional	Description
flightRequests	root	Array	M
departureInfo	flightRequests	Object	M
iataLocationCode	departureInfo	String	M	3 uppercase letters
type	departureInfo	String	O	airportcode citycode How the iataLocationCode is to be interpreted, if empty, default as airportcode
departureDate	departureInfo	String	M	YYYY-MM-DD
arrivalInfo	flightRequests	Object	M
iataLocationCode	arrivalInfo	String	M	3 uppercase letters
type	arrivalInfo	String	O	airportcode citycode How the iataLocationCode is to be interpreted, if empty, default as airportcode
arrivalDate	arrivalInfo	String	M	YYYY-MM-DD
cabinClass	flightRequests	Int	O	1 = First Class 2 = Business Class 3 = Premium Economy 4 = Economy
currency	flightRequests	String	O	Only one currency per request. Official ISO 4217 three-letter codes. https://www.iso.org/iso-4217-currency-codes.html
flightCriteria	root	Object	O	This node allows to specify flight type preference for filtering results.
flightType	flightCriteria	Int	O	1 = Direct (Non-stop) 2 = Connect (Connecting) 3 = Through (Through-flight, same flight number throughout, ground stop involved, no plane change required)
carrierCriterias	root	Array	O	This node allows you to specify query preferences to initiate a search based on specific criteria. such as supplier or airline (using airline group name) - ensuring that the results returned directly match the intended scope.
supplierName	carrierCriterias	String	O	This field allows you to specify airline group/s with multiple operating airlines or specific flight supplier/s to query relevant content.
airlineCode	carrierCriterias	String	O	Search for specific airline/carrier by using IATA airline code
agencyCode	carrierCriterias	String	O	search for specific airline agency code account
promotionCriterias	root	Array	O	A Promotion and discount code criteria to be passed to the retailer airline that could influence returned offers
promotionCode	promotionCriterias	String	O	Promotion code ID or number.
supplierName	promotionCriterias	String	O
airlineCode	promotionCriterias	String	O
agencyCode	promotionCriterias	String	O
paxList	root	Array	O	Rules: 1. Support only from 1 to 9 PAX 2. INF PAX should have a reference to one ADT PAX 3. At least 1 ADT PAX should be present 4. Number of Infants cannot be greater than Adult PAXs
paxType	paxList	String	O	Passenger Type Code: ADT TEEN CHD INF *Note: Different airlines may have varying pax type classifications and age definitions for each type. DerbySoft will provide a reference library of airline-specific passenger age criteria for Sellers. If a pax type requested by the Seller (e.g., TEEN) is not supported by the Supplier, DerbySoft will map the Seller’s requested type to a corresponding type supported by the Supplier.
count	paxList	Int	O	The number of passenger type

Response

Key	Parent	Type	Mandatory/Optional	Description
searchResults	root	Array	O
supplier	searchResults	Object	O
supplierName	supplier	String	O
airlineCode	supplier	String	O
agencyCode	supplier	String	O
technicalCapabilities	supplier	Array	O	node provides critical information about the technical execution methods and support channels available for post-booking operations with this specific supplier. This allows you to understand how different modification requests (e.g., refunds, changes) are handled behind the scenes and set the correct user expectations
operationType	technicalCapabilities	String	M	The type of post-booking operation. This field identifies which specific operation the technical details apply to (e.g., refunding a ticket, changing a flight). It scopes the context for the subsequent technical fields. DIRECT_REFUND ESTIMATED_REFUND CHANGE_FLIGHT_TIME UPDATE_PASSENGER_NAME ADD_ANCILLARY
method	technicalCapabilities	String	M	How the operation is technically executed. Key values: NATIVE_API: The supplier provides a direct, automated API. DS_AI_AGENT: Automation is enabled via an AI agent (e.g., RPA, robotic process).Note: This automated service may involve additional fees charged to the seller. MANUAL: The operation cannot be processed automatically. The seller must handle it offline by contacting the supplier or airline directly through their own channels
automationLevel	technicalCapabilities	String	M	The degree of automation. This field provides a high-level, intuitive summary of the method FULL PARTIAL NONE
apiAvailability	technicalCapabilities	String	M	This provides granular technical detail for integrators when the `method` is `NATIVE_API` REALTIME: A synchronous API that provides immediate results ASYNC: An asynchronous API; a request is submitted, and the result must be polled for later.
tripsInfo	searchResults	Object	M
tripKey	tripsInfo	String	M
onwardTrip	tripsInfo	Object	M
flightType	onwardTrip	Int	M	1 = Direct 2 = Connect 3 = Through
segmentInfos	onwardTrip	Array	M	segment information list
segmentSequence	segmentInfos	Int	M
duration	segmentInfos	Int	M
flightDesignator	segmentInfos	Object	M
marketingCarrier	flightDesignator	Object	M
marketingCarrierCode	marketingCarrier	String	M
marketingCarrierName	marketingCarrier	String	O
marketingFlightNumber	marketingCarrier	String	M
equipmentType	marketingCarrier	String	O	Aircraft equipment type
departureInfo	segmentInfos	Object	M
airportCode	departureInfo	String	M
airportName	departureInfo	String	M
terminal	departureInfo	String	O
departureDate	departureInfo	String	M	Departure date (yyyy-MM-dd)
departureTime	departureInfo	String	M	Departure time (HH:mm)
arrivalInfo	segmentInfos	Object	M
airportCode	arrivalInfo	String	M
airportName	arrivalInfo	String	M
terminal	arrivalInfo	String	O
arrivalDate	arrivalInfo	String	M	Arrival date (yyyy-MM-dd)
arrivalTime	arrivalInfo	String	M	Arrival time (HH:mm)
stopNumber	segmentInfos	Int	O	Number of stops
stops	segmentInfos	Array	O
stopSequence	stops	Int	M
airportCode	stops	String	M
airportName	stops	String	O
stayTime	stops	Int	M	Stay time in minutes
legInfos	segmentInfos	Array	O	[Since v2.0]
legSequence	legInfos	String	M	[Since v2.0] The sequential number of the leg within the segment (e.g., 1 for the first flight leg, 2 for the second leg).
departureAirport	legInfos	String	M	[Since v2.0]
arrivalAirport	legInfos	String	M	[Since v2.0]
duration	legInfos	Int	M	[Since v2.0]
equipmentType	legInfos	String	O	[Since v2.0]
properties	legInfos	Array	O	[Since v2.0]
key	properties	String	O	[Since v2.0]The identifier or name of the extended property. For example: carbon_emission
value	properties	String	O	[Since v2.0] The calculated value of the property, passed as a string. For carbon emission, it represents the single-passenger emission amount (e.g., "246").
unit	properties	String	O	[Since v2.0] The measurement unit of the property value. For carbon emission, it defaults to "kg" (Kilograms).
returnTrip	tripsInfo	Object	O	Refer to onwardTrip
airlineOffer	searchResults	Object	M
offers	airlineOffer	Array	M
supplier	offers	Object	O
offerId	offers	String	M
transInfo	offers	String	M
refTripKey	offers	String	M
brandFareName	offers	String	O
brandFareUrl	offers	String	O
brandFareCode	offers	String	O	[Since v2.0]Brand Fare Identifier Code. Replaces airline-specific concepts like bundleCode. Represents the machine-readable code of the branded fare tier (e.g., "HFL" for premium flex)
fareType	offers	String	O	[Since v2.0]
availableCount	offers	Int	O
cabinClass	offers	Int	M	1 = First Class 2 = Business Class 3 = Premium Economy 4 = Economy
supportedIssueWay	offers	String	M	HOLD INSTANT
totalPrice	offers	Object	M
totalAmount	totalPrice	String	M	The final total amount payable by the passenger. Calculation formula: TotalBaseAmount + TotalTaxFeeAmount + totalServiceFeeAmount
totalBaseAmount	totalPrice	String	M	The price of the flight ticket itself, excluding taxes and service fees. When PriceType is Gross, this amount includes commission.
totalTaxFeeAmount	totalPrice	String	M	The sum of all tax items, equal to the sum of amounts in TaxFeeDetail.
taxFeeDetails	totalPrice	Array	O
code	taxFeeDetails	String	O	The tax name
taxCode	taxFeeDetails	String	O	[Since v2.0]The code of tax
amount	taxFeeDetails	String	O
type	taxFeeDetails	String	O	Enum values: AirlineTax - Standard airline taxes VAT - Value added tax Other - Other tax types
totalServiceFeeAmount	totalPrice	String	O
serviceFeeDetails	totalPrice	Array	O
code	serviceFeeDetails	String	O	All service fees related to flight booking - including those charged by non-airline suppliers, DerbySoft.
amount	serviceFeeDetails	String	O
type	serviceFeeDetails	String	O	Enum values: Supplier - Supplier service fee DS - DerbySoft service fee
includedInTotal	serviceFeeDetails	String	O	true - Already included in TotalAmount false - Not included in TotalAmount, requires additional payment
currency	totalPrice	String	M
promotionDetailInfo	totalPrice	Object	O	[Since v2.0] Promotion details for this offer. Returned when a promotion is applied.
promoCode	promotionDetailInfo	String	M	[Since v2.0] The promotion code applied to this offer.
originalBaseAmount	promotionDetailInfo	String	M	[Since v2.0] The base fare amount before the promotion discount is applied.
discountAmount	promotionDetailInfo	String	M	[Since v2.0] The discount amount applied to the original base fare amount.
currency	promotionDetailInfo	String	M	[Since v2.0]
priceType	totalPrice	String	O	Enum values: Net - Net price, base fare excludes commission Gross - Gross price, base fare includes commission
commissionAmount	totalPrice	Object	O
amount	commissionAmount	String	O	Present when PriceType is Gross, indicates the commission amount included in the base fare.
commissionRate	commissionAmount	String	O	Present when PriceType is Gross, indicates the commission percentage.
currencyConversions	totalPrice	Array	O	Provided when any fee requires currency conversion, contains complete conversion information.
fromCurrency	currencyConversions	String	O
toCurrency	currencyConversions	String	O
rate	currencyConversions	String	O
appliedTo	currencyConversions	String	O
referenceCode	currencyConversions	String	O	The code(under service fee details node or tax fee details) for reference which this currencyConversions applied to.
originalAmount	currencyConversions	String	O
convertedAmount	currencyConversions	String	O
settlementPrices	totalPrice	Array	M	[Since v2.0] For multi-currency, this node will return all eligible settlement currency quotations.
totalBaseAmount	settlementPrices	String	M	[Since v2.0]
totalTaxFeeAmount	settlementPrices	String	M	[Since v2.0]
taxFeeDetails	settlementPrices	Array	O	[Since v2.0]
code	taxFeeDetails	String	O	[Since v2.0] The tax name
taxCode	taxFeeDetails	String	O	[Since v2.0] The tax code
amount	taxFeeDetails	String	O	[Since v2.0]
type	taxFeeDetails	String	O	[Since v2.0]Enum values: AirlineTax - Standard airline taxes VAT - Value added tax Other - Other tax types
totalServiceFeeAmount	settlementPrices	String	O	[Since v2.0]
serviceFeeDetails	settlementPrices	Array	O	[Since v2.0]
code	serviceFeeDetails	String	O	[Since v2.0] All service fees related to flight booking - including those charged by non-airline suppliers, DerbySoft.
amount	serviceFeeDetails	String	O	[Since v2.0]
type	serviceFeeDetails	String	O	[Since v2.0]Enum values: Supplier - Supplier service fee DS - DerbySoft service fee
currency	settlementPrices	String	O	[Since v2.0]
source	settlementPrices	String	O	[Since v2.0]
exchangeRate	settlementPrices	String	O	[Since v2.0]
promotionDetailInfo	settlementPrices	Object	O	[Since v2.0] Promotion details for this settlement price. Returned when a promotion is applied.
promoCode	promotionDetailInfo	String	M	[Since v2.0] The promotion code applied to this offer.
originalBaseAmount	promotionDetailInfo	String	M	[Since v2.0] The base fare amount before the promotion discount is applied.
discountAmount	promotionDetailInfo	String	M	[Since v2.0] The discount amount applied to the original base fare amount.
currency	promotionDetailInfo	String	M	[Since v2.0]
passengerFares	offers	Array	M
paxType	passengerFares	String	M
price	passengerFares	Object	O
baseAmount	price	String	O
currency	price	String	O
taxFeeAmount	price	String	O
taxFeeDetails	price	Array	O
code	taxFeeDetails	String	O	The tax name
taxCode	taxFeeDetails	String	O	[Since v2.0] The tax code
amount	taxFeeDetails	String	O
type	taxFeeDetails	String	O	Enum values: AirlineTax - Standard airline taxes VAT - Value added tax Other - Other tax types
totalAmount	price	String	O
totalServiceFeeAmount	price	String	O
serviceFeeDetails	price	Array	O
code	serviceFeeDetails	String	O	All service fees related to flight booking - including those charged by non-airline suppliers, DerbySoft.
amount	serviceFeeDetails	String	O
type	serviceFeeDetails	String	O	Enum values: Supplier - Supplier service fee DS - DerbySoft service fee
includedInTotal	serviceFeeDetails	String	O	true - Already included in TotalAmount false - Not included in TotalAmount, requires additional payment
currency	totalPrice	String	M
priceType	totalPrice	String	O	Enum values: Net - Net price, base fare excludes commission Gross - Gross price, base fare includes commission
commissionAmount	totalPrice	Object	O
amount	commissionAmount	String	O	Present when PriceType is Gross, indicates the commission amount included in the base fare.
commissionRate	commissionAmount	String	O	Present when PriceType is Gross, indicates the commission percentage.
currencyConversions	totalPrice	Array	O	Provided when any fee requires currency conversion, contains complete conversion information.
fromCurrency	currencyConversions	String	O
toCurrency	currencyConversions	String	O
rate	currencyConversions	String	O
appliedTo	currencyConversions	String	O
referenceCode	currencyConversions	String	O	The code(under service fee details node or tax fee details) for reference which this currencyConversions applied to.
originalAmount	currencyConversions	String	O
convertedAmount	currencyConversions	String	O
promotionDetailInfo	price	Object	O	[Since v2.0] Promotion details for this passenger fare. Returned when a promotion is applied.
promoCode	promotionDetailInfo	String	M	[Since v2.0] The promotion code applied to this passenger fare.
originalBaseAmount	promotionDetailInfo	String	M	[Since v2.0] The passenger base fare amount before the promotion discount is applied.
discountAmount	promotionDetailInfo	String	M	[Since v2.0] The discount amount applied to the original passenger base fare amount.
currency	promotionDetailInfo	String	M	[Since v2.0]
settlementPrices	price	Array	M	[Since v2.0] For multi-currency, this node will return all eligible settlement currency quotations.
totalBaseAmount	settlementPrices	String	M	[Since v2.0]
totalTaxFeeAmount	settlementPrices	String	M	[Since v2.0]
taxFeeDetails	settlementPrices	Array	O	[Since v2.0]
code	taxFeeDetails	String	O	[Since v2.0] The tax name
taxCode	taxFeeDetails	String	O	[Since v2.0] The tax code
amount	taxFeeDetails	String	O	[Since v2.0]
type	taxFeeDetails	String	O	[Since v2.0]Enum values: AirlineTax - Standard airline taxes VAT - Value added tax Other - Other tax types
totalServiceFeeAmount	settlementPrices	String	O	[Since v2.0]
serviceFeeDetails	totalPrice	Array	O	[Since v2.0]
code	serviceFeeDetails	String	O	[Since v2.0] All service fees related to flight booking - including those charged by non-airline suppliers, DerbySoft.
amount	serviceFeeDetails	String	O	[Since v2.0]
type	serviceFeeDetails	String	O	[Since v2.0] Enum values: Supplier - Supplier service fee DS - DerbySoft service fee
currency	settlementPrices	String	O	[Since v2.0]
source	settlementPrices	String	O	[Since v2.0]
exchangeRate	settlementPrices	String	O	[Since v2.0]
promotionDetailInfo	settlementPrices	Object	O	[Since v2.0] Promotion details for this settlement price. Returned when a promotion is applied.
promoCode	promotionDetailInfo	String	M	[Since v2.0] The promotion code applied to this passenger fare.
originalBaseAmount	promotionDetailInfo	String	M	[Since v2.0] The passenger base fare amount before the promotion discount is applied.
discountAmount	promotionDetailInfo	String	M	[Since v2.0] The discount amount applied to the original passenger base fare amount.
currency	promotionDetailInfo	String	M	[Since v2.0]
supportedDocumentType	passengerFares	String	O	Travel Document Types P: Passport
passengerIdentifyDocumentsRequired	passengerFares	Boolean	O
fareComponents	passengerFares	Array	M
onwardTrip	fareComponents	Object	M
segmentInfos	onwardTrip	Array	M
segmentSequence	segmentInfos	String	O
fareBasisCode	segmentInfos	String	O
bookingCode	segmentInfos	String	O
amenities	segmentInfos	Object	O
wifi	amenities	Object	O
available	wifi	String	O	Boolean value: true/false
seat	amenities	Object	O
type	seat	String	O
legroom	seat	String	O
power	amenities	Object	O
available	power	String	O	Boolean value: true/false
conditions	onwardTrip	Array	O
freeServices	onwardTrip	Array	O
serviceType	freeServices	String	O	The category of the ancillary service： Meal Priority Boarding Special Assistance Seat Sport Equipment Carbon Offset
desc	freeServices	String	O
serviceName	freeServices	String	O	[Since v2.0]
needSelection	freeServices	String	O	[Since v2.0] Selection Requirement Indicator. Indicates whether the included complimentary service requires explicit selection during booking or pre-booking (e.g., true for choosing seat designator/meal type; false for automatic benefits like priority boarding).
ssrCode	freeServices	String	O	[Since v2.0] Standard SSR Code. Transparently carries the underlying Special Service Request code
limitedPerPsg	freeServices	String	O	[Since v2.0]
freeBaggages	onwardTrip	Array	O
typeCode	freeBaggages	String	O
descText	freeBaggages	String	O
ssrCode				[Since v2.0]
maximumDimensionAllowance	freeBaggages	Object	O
heightMeasure	maximumDimensionAllowance
lengthMeasure	maximumDimensionAllowance
linearMeasure	maximumDimensionAllowance
widthMeasure	maximumDimensionAllowance
unitOfMeasurement	maximumDimensionAllowance
pieceAllowance	freeBaggages
totalQty	pieceAllowance
weightAllowance	freeBaggages
maximumWeightMeasure	weightAllowance
weightUnitOfMeasurement	weightAllowance
totalWeightMeasure	weightAllowance
price	onwardTrip	Object	O	[Since v2.0] Added to return onward trip price and return trip price. The structure is same with passengerFare.price
returnTrip	fareComponents	Object	M
ssrs	offers	Array	O	SSRS node is designed to return available optional paid ancillary services that passengers can purchase in addition to their flight ticket
service	ssrs	Object	M
serviceName	service	String	M	The commercial name of the service as displayed to passengers
serviceType	service	String	M	The category of the ancillary service： Baggage Meal Priority Boarding Special Assistance Seat Sport Equipment
availability	service	String	O	Indicates current available numbers of the service
data	serviceOrder	Object	O
baggageAssociations	data	Object	O	This node is ONLY present when serviceType = 'BAGGAGE'. Contains baggage-specific details
baggageId	baggageAssociations	String	O
typeCode	baggageAssociations	String	O	Type of baggage CheckedIn CarryOn
descText	baggageAssociations	String	O
maximumDimensionAllowance	baggageAssociations	Object	O
heightMeasure	maximumDimensionAllowance	String	O	Maximum allowed height of the baggage
lengthMeasure	maximumDimensionAllowance	String	O	Maximum allowed length of the baggage.
linearMeasure	maximumDimensionAllowance	String	O	Maximum allowed linear dimensions (sum of dimensions)
widthMeasure	maximumDimensionAllowance	String	O	Maximum allowed width of the baggage
unitOfMeasurement	maximumDimensionAllowance	String	O	Unit of measurement for dimensions (e.g., CM, IN)
pieceAllowance	baggageAssociations	Object	O
totalQty	pieceAllowance	String	M	Total number of baggage pieces allowed
weightAllowance	baggageAssociations	String	M
maximumWeightMeasure	weightAllowance	String	M	Maximum allowed weight per baggage piece
weightUnitOfMeasurement	weightAllowance	String	M	Unit of measurement for weight (e.g., KG, LB)
totalWeightMeasure	weightAllowance	String	O	Total maximum weight allowed for the baggage allowance. Used when the allowance is based on total weight across pieces.
seat	data	Object	O
seatId	seat	String	O
designator	seat	String	O	Referred to as airline code
deck	seat	String	O	Indicates the level or deck of the aircraft where the seat is located. Main: for the primary cabin deck Upper: for the upper deck
rowNo	seat	String	O	Specifies the row number of the seat
colNo	seat	String	O	Specifies the column position or seat letter within the row
seatTypes	seat	Array	O	The characteristics and features of the seat. This field uses standardized codes: WINDOW AISLE EXIT MIDDLE EXTRA_LEG_ROOM HANDICAP_ACCESSIBLE: wheelchair accessible seat
servicePsgFare	ssrs
paxType	servicePsgFare
unitPrice	servicePsgFare
totalAmount	unitPrice
servicePsgFare	unitPrice
eligibleTrips	ssrs	Object	M	Indicates which specific trip segments this service applies to. Multiple serviceOffers are returned when a service is available for different trips.
onwardTrip	eligibleTrips	Object	O
segmentSequence	onwardTrip	Array	O	Segment sequence numbers in the onward trip that this service applies to
returnTrip	eligibleTrips	Object	O
segmentSequence	onwardTrip	Array	O	Segment sequence numbers in the return trip that this service applies to
eligibleLeg	ssrs	Object	O	For multi-leg segments (flights with stopovers), specifies which specific leg within a segment the service applies to. Empty for non-stop flights.
legSequence	eligibleLeg	String	M
error	root	Object	O

Each search result consists of two primary components: the trip information (tripinfo) and the available offers.
- The tripinfo section primarily contains the itinerary details, including but not limited to departure and arrival times, marketing carrier, and operating carrier.
- The offers section, meanwhile, provides the comprehensive pricing for the entire itinerary (e.g., the total cost for one adult and one child if requested), a breakdown of fares by passenger type, along with details on bundled services and the associated change and cancellation policies.
OfferID Persistence
- The offerId within the offer object is a mandatory unique identifier for the specific itinerary.
- You must store this value. It is a required reference key for subsequent API calls, specifically the OfferPrice and OrderCreate requests, to uniquely identify the chosen offer.

AirShopping

TRequest Payload Example

Request Payload Structure

Response