openapi: 3.0.1
info:
title: HolidayOffersController API
description: "Supported versions for the X-API-VERSION header is: v1, v2"
version: v1
contact:
name: Sales-Starlight-TEAM
url: "https://developer.tui/api-catalog/holidayofferscontroller-api"
email: starlight@TUIGroup.onmicrosoft.com
servers:
- url: https://prod.api.tui/search-holiday-offers
paths:
/search-holiday-offers/search/package/v1/offers:
post:
tags:
- HolidayOffersController USL API
summary: Get holiday offers (v1)
description: |
v1 is the USL version for the Holidays Offers API. Returns Package holidays based on
the search criteria in the request body. Support filter retention. More could find here:
https://confluence.tuigroup.com/pages/viewpage.action?pageId=1474581073#DesignUSLAPIforlistofferproxysupportingWR/NR-ProposedStoriesfortheListOffersTeamtoimplementnewchanges
parameters:
- name: x-source-application
in: header
required: true
description: Source application for this request flow
schema:
type: string
example: "Search Results MFE"
- name: x-correlation-id
in: header
required: true
description: UUID to identify a specific request in case of an issue. End to end tracing ID
schema:
type: string
format: uuid
example: "14bafa8a-182d-4390-bc91-11e79bdcaec0"
- name: x-environment
in: header
schema:
$ref: "#/components/schemas/Environment"
- name: x-ab-cookie-set
in: header
description: List of AB test cookies to be sent to NGS
schema:
type: string
example: "1080:A,1081:B"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SearchOfferRequest"
required: true
responses:
"200":
description: Successful search of the offers 200 response
content:
application/json:
schema:
$ref: "#/components/schemas/SearchOfferResponse"
"204":
description: Successful search of the offers, but no offers is present
"400":
description: Bad Request
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ValidationProblem"
"404":
description: Resource Not Found
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
"500":
description: Internal Server Error. Something went wrong on our end
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
"502":
description: Bad Gateway. One or more backend systems not available
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
"504":
description: Gateway Timed Out
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
/search-holiday-offers/search/package/v1/unique-offer:
post:
tags:
- Unique offer USL API
summary: Get unique offer (v1)
description: v1 is the USL version of unique offer API which will be used to get price and availability of particular package on entry of unit details page and handshake between search and book
operationId: getPriceOffer
parameters:
- name: x-correlation-id
in: header
required: true
schema:
type: string
format: uuid
example: "14bafa8a-182d-4390-bc91-11e79bdcaec0"
description: UUID to identify a specific request in case of an issue. End to end tracing ID
- name: x-environment
in: header
schema:
$ref: "#/components/schemas/Environment"
description: "Environment for which the request has to be made in backend, if env is not passed then following will be default values at USL end - dev: hybdv8, sit: st3, pprd: pprd"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UniqueOfferRequest"
required: true
responses:
"200":
description: getListOffers 200 response
headers:
x-environment:
description: Environment from which the response come back from backend
schema:
$ref: "#/components/schemas/Environment"
content:
application/json:
schema:
$ref: "#/components/schemas/UniqueOfferResponse"
"204":
description: Successful search of the offers, but no offers is present
"400":
description: Bad Request
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ValidationProblem"
/search-holiday-offers/search/package/v1/price-calendar:
post:
tags:
- "Price calendar search"
summary: |-
API for region agnostic request for prices based on filters for specific accommodation in the package
Currently support NR and WR
description: >
This API is used to retrieve prices for period of time for single accommodation based on defined search criteria
operationId: getPriceCalendarUSL
parameters:
- name: "x-correlation-id"
in: header
required: true
description: UUID to identify a specific request in case of an issue. End to end tracing ID
schema:
type: string
default: none
- name: x-environment
in: header
schema:
$ref: "#/components/schemas/Environment"
description: "Environment for which the request has to be made in backend, if env is not passed then following will be default values at USL end - dev: hybdv8, sit: st3, pprd: pprd"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/PriceCalendarRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/PriceCalendarResponse"
"400":
description: Invalid input parameters
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
"500":
description: Internal server error
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
"404":
description: Resource not found
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
"204":
description: No Content - The request was successful, but there is no content to return
content: {} # This explicitly specifies that there's no content in the response body
components:
schemas:
ValidationProblem:
type: object
properties:
problem:
$ref: "#/components/schemas/Problem"
validationIssues:
type: array
items:
type: string
Problem:
type: object
properties:
type:
type: string
system:
type: string
title:
type: string
details:
type: string
SearchOfferRequest:
required:
- numberOfNights
- dateRange
- alternateDurations
- travellers
- commercialProductType
- sortBy
- metaInformation
type: object
x-field-extra-annotation:
- "@Introspected"
properties:
alternateDurations:
type: array
description: "Alternative number of nights to find offers for. These should be in order of preference: first we should attempt the first duration, and we only consider duration index i+1 if we cannot find any offers for duration index i. Note that this list WILL include the `preferredNumberOfNights`!"
example: [8, 6, 7, 9, 5, 10, 11]
maxItems: 8
minItems: 1
items:
type: integer
example: 7
minimum: 1
maximum: 99
description: Number of nights the customer would stay at the hotel.
numberOfNights:
minimum: 1
type: number
format: integer
description: Selected number of nights
from:
type: array
items:
$ref: "#/components/schemas/SearchRequestDeparture"
to:
type: array
items:
$ref: "#/components/schemas/SearchRequestDestination"
dateRange:
$ref: "#/components/schemas/SearchRequestDateRange"
unitAllocations:
type: array
items:
$ref: "#/components/schemas/SearchRequestUnitAllocation"
travellers:
type: array
items:
$ref: "#/components/schemas/Traveller"
x-field-extra-annotation: '@field:Size(min = 1, message = "Travellers is a mandatory field. Must contain at least one item")'
commercialProductType:
$ref: "#/components/schemas/CommercialProductType"
sortBy:
$ref: "#/components/schemas/SearchRequestSortType"
pageSize:
minimum: 1
type: integer
format: int32
description: Number of results per page
pageNumber:
minimum: 1
type: integer
format: int32
description: Number of requested page
metaInformation:
$ref: "#/components/schemas/SearchRequestMetaInformation"
filters:
type: array
x-field-extra-annotation:
- "@Valid"
items:
$ref: "#/components/schemas/Filter"
excludeTypes:
type: array
items:
type: string
description: The holiday type which needs to be excluded from response
example: "TOUR"
CommercialProductType:
type: string
enum:
- SUN_AND_BEACH
- LAKES_AND_MOUNTAINS
- CITY
SearchOfferResponse:
type: object
x-field-extra-annotation:
- "@Introspected"
required:
- filters
- holidays
properties:
filters:
type: array
x-field-extra-annotation:
- "@Valid"
items:
$ref: "#/components/schemas/Filter"
holidays:
x-field-extra-annotation:
- "@Valid"
$ref: "#/components/schemas/PackageHoliday"
Filter:
type: object
example: '[{
"code": "DESTINATIONS",
"value": "Destination",
"options": [
{
"code": "ESP",
"available": true,
"selected": false,
"value": "Spain",
"type": "COUNTRY",
"options": [
{
"code": "002894",
"value": "Andalucia",
"selected": false,
"count": 66,
"type": "REGION",
"available": true,
"options": [
{
"code": "002894",
"value": "Andalucia Child(example)",
"selected": false,
"count": 33,
"type": "DESTINATION",
"available": true
},
{
"code": "002894",
"value": "Andalucia Child(example)",
"selected": false,
"count": 33,
"type": "DESTINATION",
"available": true
}
]
},
{
"code": "000373",
"value": "Barcelona",
"selected": false,
"count": 117,
"type": "DESTINATION",
"available": true
}
}]'
required:
- code
- options
properties:
code:
$ref: "#/components/schemas/FilterType"
value:
type: string
nullable: false
example: Departure Points
description: Naming of the filter, if the naming not present should be filter type then
options:
type: array
x-field-extra-annotation:
- "@Valid"
- "@NotEmpty"
items:
$ref: "#/components/schemas/FilterOption"
FilterOption:
type: object
x-field-extra-annotation:
- "@Valid"
required:
- code
- selected
properties:
code:
type: string
nullable: false
description: Code of the filter option,
for CARRIER filter type it could be - TOM
for BOARDBASIS filter type it could be - AI
etc
example: "G-000000703" #Nordic Barcelona code
count:
type: integer
format: int32
minimum: 0
default: 0
description: Number of hotel offers with this filter option
example: 15
available:
type: boolean
example: true
description:
Defines availability of the option, required for the filter retention,
when for example certain options no longer part of the response from NGS, that it should be false
selected:
x-field-extra-annotation:
- "@NotNull"
type: boolean
nullable: true
description: Defines what option is selected or not,
selection value should be retained,
selected values should be sent to the NGS as a filter criteria
example: true
value:
type: string
description: localised name of the filter option
example: Balearic Islands
options:
type: array
x-field-extra-annotation:
- "@Valid"
items:
$ref: "#/components/schemas/FilterOption"
description: hierarchy items
type:
$ref: "#/components/schemas/FilterOptionType"
description:
type: string
description: description of the filter option
example: For the SC code (board basis filter) - Meals aren’t included, but you’ll have catering facilities.
shortDescription:
type: array
items:
$ref: "#/components/schemas/ListOfferShortDescription"
FilterOptionType:
type: string
enum:
- HOTEL
- COUNTRY
- DESTINATION
- RESORT
- REGION
- CONCEPT
- ITINERARY
- CONTINENT
description: needed for the specifying destination type.
example: COUNTRY
SearchRequestSortType:
type: string
description: Sort order to use before paging
example: TOTALPRICEASC
enum:
- DEFAULT
- TOTALPRICEASC
- TOTALPRICEDESC
- REVIEWDESC
- CUSTOMERRATING
- DISCOUNTDESC
- FLIGHTDEPTIMESASC
SearchRequestDestination:
required:
- code
- type
type: object
properties:
code:
type: string
example: A0418356
description: code of the destination, like country code or accommodation code
type:
$ref: "#/components/schemas/FilterOptionType"
SearchRequestDeparture:
type: object
properties:
code:
type: string
description: Airport IATA code
pattern: "[A-Z]{3}"
example: BRU
type:
type: string
pattern: "(AIRPORT)"
description: type from where we go, currently it is only AIRPORT
example: AIRPORT
SearchRequestMetaInformation:
required:
- brand
- medium
- target
- sourceMarket
- locale
- currency
type: object
properties:
target:
$ref: "#/components/schemas/SellingTarget"
sourceMarket:
$ref: "#/components/schemas/SourceMarket"
brand:
$ref: "#/components/schemas/Brand"
provider:
type: string
default: TUI
description:
Provider Code, use "TUI" as a default unless specified otherwise
WR only. //Could be removed?
example:
medium:
$ref: "#/components/schemas/Medium"
agentId:
type: string
example: "T|D2816,F|D2816"
description: one or more comma-separated agent or abta codes, required for 'retail' NR channel. Retail inhouse/3rd party agent id
locale:
type: string
pattern: ^[a-z]{2}_[A-Z]{2}$
example: nl_BE
description: locale information
currency:
$ref: "#/components/schemas/Currency"
Currency:
type: object
description: currency information
required:
- currencyCode
properties:
currencyCode:
type: string
example: USD
minLength: 3
maxLength: 3
description: 3 letter currency code
SearchRequestUnitAllocation:
required:
- number
- paxAge
- paxID
- unitType
type: object
minItems: 1
properties:
paxID:
minimum: 1
type: number
format: integer
description: id of the pax
example: 1
paxAge:
minimum: 0
type: number
format: integer
description: age of the pax
example: 18
number:
minimum: 1
type: number
format: integer
description: in which room pax goes, room number
example: 1
unitType:
$ref: "#/components/schemas/UnitAllocationType"
AccommodationControllerResponse:
deprecated: true
required:
- checkinDate
- name
- overview
- productComponentGroupIndex
type: object
properties:
code:
type: string
name:
type: string
numberOfNights:
type: integer
format: int32
checkinDate:
type: string
productComponentGroupIndex:
type: integer
format: int32
units:
type: array
items:
$ref: "#/components/schemas/UnitResponse"
concepts:
type: array
items:
$ref: "#/components/schemas/Concept"
overview:
$ref: "#/components/schemas/Overview"
Brand:
type: string
description: Brand code
enum:
- TUI_BE
- TUI_NL
- VIP_BE
- TUI_UK
- TUI_IE
- FIRST_CHOICE
- TUI_SE
- TUI_DK
- TUI_FI
- TUI_NO
CancellationRuleResponse:
type: object
properties:
type:
type: string
description: type of the cancellation rule
example: "FREE"
amount:
type: number
format: double
description: amount to pay if cancellation rule is not FREE
example: 0
daysAfterBooking:
type: string
description: amount of days after booking to allow free cancellation
example: "15"
daysBeforeDeparture:
type: string
description: applicable days before departure should be met to allow cancellation rule
example: "70"
CanxResponse:
deprecated: true
required:
- isApplicable
type: object
properties:
applicableTill:
type: string
cancellationRuleId:
type: string
cancellationRule:
type: array
items:
$ref: "#/components/schemas/CancellationRuleResponse"
isApplicable:
type: boolean
ChannelControllerResponse:
deprecated: true
required:
- brand
- medium
- siteId
- sourceMarket
- target
type: object
properties:
siteId:
type: string
target:
type: string
sourceMarket:
type: string
brand:
type: string
medium:
type: string
Concept:
deprecated: true
type: object
properties:
code:
type: string
name:
type: string
SearchRequestDateRange:
required:
- from
- to
type: object
properties:
from:
type: string
nullable: false
example: "2026-11-01"
description: start date from
to:
type: string
nullable: false
example: "2026-11-11"
description: start date to(till)
DaysAfterBookingResponse:
deprecated: true
type: object
properties:
to:
type: string
DaysBeforeDeparture:
deprecated: true
type: object
properties:
from:
type: string
FactResponse:
deprecated: true
required:
- fee
- key
- name
- text
type: object
properties:
text:
type: string
key:
type: string
name:
type: string
fee:
type: boolean
FilterType:
type: string
description: type of the filter
example: TRIPRATING
enum:
- BOARDBASIS
- TUIRATING
- FACILITIES
- CONCEPTS
- HOLIDAYDEPARTUREDATE
- HOLIDAYTYPE
- ACCOMMODATIONTYPE
- PRICE
- PRICEPP
- DISCOUNT
- DESTINATIONS
- DURATIONS
- DISTANCETO
- DEPARTUREAIRPORTS
- CUSTOMERRATING
- COMMISSIONMARKERS
- TRIPRATING
- CARRIER
- BESTFOR
- DEPARTURETIMEOUT
- DEPARTURETIMEBACK
- FREECHILDPLACES
- ACCESSIBILITY
- FLIGHTSTOPS #(like Charter, Direct, etc)
- MOUNTAINFEATURES
- FLIGHTTYPE #(like tpa - 3pa flights)
FlightComponentResponse:
deprecated: true
required:
- arrivalAirport
- arrivalAirportName
- arrivalDate
- arrivalTime
- carrierCode
- departureAirport
- departureAirportName
- departureDate
- departureTime
- dir
- flightNumber
- flightSourcing
- journeyId
- operatingCarrierCode
- productUnitId
- sourcingSystem
type: object
properties:
dir:
type: string
departureAirport:
type: string
departureAirportName:
type: string
departureDate:
type: string
departureTime:
type: string
arrivalAirport:
type: string
arrivalAirportName:
type: string
arrivalDate:
type: string
arrivalTime:
type: string
journeyDuration:
type: integer
format: int32
productComponentGroupIndex:
type: integer
format: int32
carrierCode:
type: string
flightNumber:
type: string
journeyId:
type: string
flightSourcing:
type: string
sourcingSystem:
type: string
operatingCarrierCode:
type: string
productUnitId:
type: string
availability:
type: integer
format: int32
flightLegs:
type: array
items:
$ref: "#/components/schemas/FlightLegFlightComponent"
FlightLegFlightComponent:
deprecated: true
required:
- arrivalAirport
- arrivalDate
- arrivalTime
- departureAirport
- departureDate
- departureTime
- fltNo
- inventoryLegKey
- legDuration
- marketingCarrier
- operatingCarrier
- operatingFlightNumber
- productComponentGroupIndex
type: object
properties:
legNumber:
type: integer
format: int32
legDuration:
type: integer
format: int32
inventoryLegKey:
type: string
productComponentGroupIndex:
type: integer
format: int32
operatingFlightNumber:
type: string
departureAirport:
type: string
departureDate:
type: string
departureTime:
type: string
arrivalAirport:
type: string
arrivalDate:
type: string
arrivalTime:
type: string
journeyDuration:
type: integer
format: int32
fltNo:
type: string
marketingCarrier:
type: string
operatingCarrier:
type: string
availability:
type: integer
format: int32
GeoResponse:
deprecated: true
required:
- id
- name
- type
type: object
properties:
id:
type: string
name:
type: string
type:
type: string
HolidayType:
deprecated: true
type: string
enum:
- BEACH
- CITY
- LAKES
Holidays:
deprecated: true
required:
- autoSelectedNights
- firstItemNum
- lastItemNum
- totalItemsCount
type: object
properties:
totalItemsCount:
type: integer
format: int32
firstItemNum:
type: integer
format: int32
lastItemNum:
type: integer
format: int32
autoSelectedNights:
type: array
items:
type: string
offers:
type: array
items:
$ref: "#/components/schemas/OfferResponse"
PackageHoliday:
required:
- totalItemsCount
type: object
properties:
totalItemsCount:
type: integer
format: int32
default: 0
description: total number of the results for search criteria
example: 316
offers:
type: array
description: paginated offers response information
items:
$ref: "#/components/schemas/PackageOfferResponse"
ImageResponse:
deprecated: true
required:
- url
type: object
properties:
url:
type: string
caption:
type: string
category:
type: string
ListOfferChannel:
deprecated: true
required:
- brand
- medium
- provider
- siteID
- sourceMarket
- target
type: object
properties:
siteID:
$ref: "#/components/schemas/SiteID"
target:
$ref: "#/components/schemas/SellingTarget"
sourceMarket:
$ref: "#/components/schemas/SourceMarket"
brand:
$ref: "#/components/schemas/Brand"
provider:
type: string
medium:
$ref: "#/components/schemas/Medium"
ListOfferDestination:
deprecated: true
required:
- code
- type
type: object
properties:
code:
type: string
type:
$ref: "#/components/schemas/ToType"
ListOfferFrom:
deprecated: true
required:
- code
- type
type: object
properties:
code:
type: string
type:
type: string
ListOfferOption:
deprecated: true
required:
- code
type: object
properties:
code:
type: string
count:
type: integer
format: int32
available:
type: boolean
selected:
type: boolean
value:
type: string
options:
type: array
items:
$ref: "#/components/schemas/ListOfferOption"
description:
type: string
shortDescription:
type: array
items:
$ref: "#/components/schemas/ListOfferShortDescription"
ListOfferReqShortDescription:
deprecated: true
required:
- markdown
type: object
properties:
markdown:
type: string
category:
type: string
title:
type: string
ListOfferShortDescription:
type: object
properties:
markdown:
type: string
category:
type: string
title:
type: string
ListOfferTransferUnit:
deprecated: true
required:
- availability
- productUnitId
- sourceUnitId
- sourcingCategory
- transferCategory
- transferType
- transferTypeCode
- unitAllocations
type: object
properties:
availability:
type: integer
format: int32
freeChildPlace:
type: boolean
productUnitId:
type: string
sourceUnitId:
type: string
sourcingCategory:
type: string
transferTypeCode:
type: string
transferCategory:
type: string
transferType:
type: string
unitAllocations:
type: array
items:
$ref: "#/components/schemas/TransferUnitAllocations"
Medium:
type: string
description: Medium code, WR required
enum:
- TUI_STORE
- MOBILE_AGENT
- THIRD_PARTY_AGENT
- CSC
- CUSTOMER_UI
- OTA
- TUI_PARTNER
- TUI_STAFF
- TUI_BUSINESS
- SHARER
- GDS
- TUI_APP
OfferResponse:
deprecated: true
required:
- canx
- channel
- holidayEndDate
- holidayStartDate
- price
- productID
- transport
type: object
properties:
productID:
type: string
holidayStartDate:
type: string
holidayEndDate:
type: string
channel:
$ref: "#/components/schemas/ChannelControllerResponse"
commercialPriority:
type: integer
format: int32
commercialProductType:
type: string
price:
$ref: "#/components/schemas/Price"
accommodations:
type: array
items:
$ref: "#/components/schemas/AccommodationControllerResponse"
transport:
$ref: "#/components/schemas/TransportResponse"
transfers:
type: array
items:
$ref: "#/components/schemas/Transfer"
canx:
$ref: "#/components/schemas/CanxResponse"
PackageOfferResponse:
required:
- holidayEndDate
- holidayStartDate
- prices
- id
- flight
- accommodations
type: object
properties:
id:
type: string
description: product id for WR / atcom pkg id for NR
example: WR = "ad86b620-7085-45da-a8c3-37eb07d8763b"; NR = "3445560/3/559/7"
code:
type: string
description: accommodation offer id (NR)
example: WR = "ad86b620-7085-45da-a8c3-37eb07d8763b"; NR = "EGSH0019"
name:
type: string
description: Accommodation name
example: "TUI BLUE Nastro Azzurro"
holidayStartDate:
type: string
format: date
description: start date of the holiday offer
example: "2025-07-15"
holidayEndDate:
type: string
format: date
description: end date of the holiday offer
example: "2025-07-25"
lowDeposit:
type: boolean
default: false
description: is the low deposit information is available in offer. applicable only in NR
example: true
packageId:
type: string
deprecated: true
description:
id for the particular package for this unit - required only for NR |
generation details https://confluence.tuigroup.com/pages/viewpage.action?spaceKey=ENGDO&title=Package+id+generation+logic
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tui-group/refs/heads/main/openapi/tui-group-tui-holiday-offers-controller-api-openapi.yml