TUI Cruise Price and Availability API (Cruise Offers v1.0)

openapi: 3.0.3
info:
  title: TUI Cruise Price and Availability.
  description: These APIs returns price and availability for given search criteria
  version: "1.0"
  contact:
    email: cruise-api-support@TUIGroup.onmicrosoft.com
    name: "Cruise API Support"
  x-header: |
    This APIs returns cruises prices and availability for given search criteria.
  x-summary: |
    This API returns range of availability and pricing information that is specific to the search criteria.
    This API returns offer details and pricing information for a specific itinerary, date range, and duration.
    This API returns availability and pricing information for alternate cabins and boards.
    This API returns availability and pricing information of alternative flights for a specific cruise package.
    This API returns availability and pricing information of alternative stay variants for a specific cruise package.

servers:
  - url: https://prod.api.tui/cruisepriceresults
paths:
  /v1/cruises/offers:
    post:
      tags:
        - "Cruise Search"
      summary: |-
        API to get the price and availability
      description: >
        The purpose of this API is to offer users a comprehensive range of availability and pricing information that is specific to their search criteria requirements. This includes details such as departure points, destinations, date range, duration, and passenger numbers.
      operationId: getCruisePackagePrices
      parameters:
        - name: "x-Trace-Id"
          in: header
          required: true
          description: End to end tracing ID, can be any string
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{10,15}$
            example: OQ9Eu77laT
        - name: "env"
          in: header
          required: false
          description: A unique environment identifier for request to retrieve from correct ngs instance
          schema:
            type: string
            example: dev,test
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CruiseOffersRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CruiseHolidays"
        "400":
          description: Invalid input parameters
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ValidationProblem"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "502":
          description: Bad Gateway
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "504":
          description: Gateway Timed Out
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: Unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /v1/cruises/unique/offer:
    post:
      tags:
        - "Cruise Unique Search"
      summary: |-
        API to get the price and availability of unique cruise
      description: >
        This API has been developed to provide users with a comprehensive check of the availability and pricing information for a specific itinerary, date range, and duration. It allows users to provide details of a single cruise holiday package, including sailing, flight, and stay information, and returns the pricing and availability of the same package. This API is particularly useful for verifying a selected package from the Offers API, ensuring that users have all the necessary information before making a decision.
      operationId: getUniqueCruisePackagePrices
      parameters:
        - name: "x-Trace-Id"
          in: header
          required: true
          description: End to end tracing ID, can be any string
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{10,15}$
            example: OQ9Eu77laT
        - name: "env"
          in: header
          required: false
          description: A unique environment identifier for request to retrieve from correct ngs instance
          schema:
            type: string
            example: dev,test
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CruiseUniqueRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CruiseOffers"
        "400":
          description: Invalid input parameters
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ValidationProblem"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "502":
          description: Bad Gateway
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "504":
          description: Gateway Timed Out
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: Unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /v1/cruises/cabin-board-variants:
    post:
      tags:
        - "Cruise Alternate Cabin and Board Search"
      summary: |-
        API to get the alternate cabin and boards
      description: >
        This API is designed to retrieve the availability and pricing information for alternate cabins based on the itinerary, date range, and duration provided. 
        It's important to note that the API is unable to handle more than one cabin at a time. Therefore, if you want to request alternate cabins for multiple cabins, 
        you must make separate requests for each cabin allocation.
        For instance, if you select two cabins, you need to make two separate requests, one for each cabin.
      operationId: getAlternateCabinAndBoards
      parameters:
        - name: "x-Trace-Id"
          in: header
          required: true
          description: End to end tracing ID, can be any string
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{10,15}$
            example: OQ9Eu77laT
        - name: "env"
          in: header
          required: false
          description: A unique environment identifier for request to retrieve from correct ngs instance
          schema:
            type: string
            example: dev,test
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CruiseUniqueRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CruiseAlternateCabinAndBoardOffers"
        "400":
          description: Invalid input parameters
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ValidationProblem"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "502":
          description: Bad Gateway
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "504":
          description: Gateway Timed Out
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: Unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /v1/cruises/flight-variants:
    post:
      tags:
        - "Cruise Alternate Flight Variant Search"
      summary: |-
        API to get alternate flight variant for the selected packages
      description: >
        This API is designed to retrieve information on the availability and pricing of alternative flights for a specific cruise package. It allows users to input details of a single cruise holiday package, including sailing, flight, and stay information. In return, users receive details on the pricing and availability of alternative flight packages.
      operationId: getAlternateFlightVariants
      parameters:
        - name: "x-Trace-Id"
          in: header
          required: true
          description: End to end tracing ID, can be any string
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{10,15}$
            example: OQ9Eu77laT
        - name: "env"
          in: header
          required: false
          description: A unique environment identifier for request to retrieve from correct ngs instance
          schema:
            type: string
            example: dev,test
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CruiseFlightVariantRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CruiseFlightVariants"
        "400":
          description: Invalid input parameters
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ValidationProblem"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "502":
          description: Bad Gateway
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "504":
          description: Gateway Timed Out
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: Unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /v1/cruises/stay-variants:
    post:
      tags:
        - "Cruise Alternate Stay Variant Search"
      summary: |-
        API to get alternate stay variant for the selected packages
      description: >
        This API is designed to retrieve information on the availability and pricing of alternative flights for a specific cruise package. It allows users to input details of a single cruise holiday package, including sailing, flight, and stay information. In return, users receive details on the pricing and availability of alternative stay packages.
      operationId: getAlternateStayVariants
      parameters:
        - name: "x-Trace-Id"
          in: header
          required: true
          description: End to end tracing ID, can be any string
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{10,15}$
            example: OQ9Eu77laT
        - name: "env"
          in: header
          required: false
          description: A unique environment identifier for request to retrieve from correct ngs instance
          schema:
            type: string
            example: dev,test
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CruiseStayOfferRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CruiseStayVariants"
        "400":
          description: Invalid input parameters
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ValidationProblem"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "502":
          description: Bad Gateway
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "504":
          description: Gateway Timed Out
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: Unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
  /v1/cruises/stay-upsell-options:
    post:
      tags:
        - "Cruise Add a stay"
      summary: |-
        API to cross-sell stay for the selected packages
      description: >
        This API is designed to cross-sell stay for cruise types, for e.g. provide stay for cruise packages and provide alternate stays for cruise & stay packages.
      operationId: addAStay
      parameters:
        - name: "x-Trace-Id"
          in: header
          required: true
          description: End to end tracing ID, can be any string
          schema:
            type: string
            pattern: ^[A-Za-z0-9]{10,15}$
            example: OQ9Eu77laT
        - name: "env"
          in: header
          required: false
          description: A unique environment identifier for request to retrieve from correct ngs instance
          schema:
            type: string
            example: dev,test
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CruiseStayUpsellOfferRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CruiseStayUpsellOfferResponse"
        "400":
          description: Invalid input parameters
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ValidationProblem"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "502":
          description: Bad Gateway
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "504":
          description: Gateway Timed Out
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        default:
          description: Unexpected error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
components:
  schemas:
    CruiseOffersRequest:
      type: object
      required:
        - metaInformation
        - departureAirports
        - dateRange
        - cruiseDuration
        - travellers
      properties:
        metaInformation:
          $ref: "#/components/schemas/MetaInformation"
        departureAirports:
          $ref: "#/components/schemas/Airports"
        to:
          $ref: "#/components/schemas/Destinations"
        cruiseDuration:
          title: Cruise sailing duration in number of nights
          type: integer
          format: int32
          example: 7
        stayDuration:
          $ref: "#/components/schemas/StayDuration"
        dateRange:
          $ref: "#/components/schemas/DateRange"
        travellers:
          type: array
          items:
            $ref: "#/components/schemas/Traveller"
        cabins:
          $ref: "#/components/schemas/Cabins"
        resultsPerPage:
          type: integer
          format: int32
          minimum: 1
          maximum: 10
        pageNumber:
          type: integer
          format: int32
          minimum: 1
        filters:
          type: object
          properties:
            cruiseDestinations:
              type: array
              description: Cruise sailing geo location codes
              items:
                type: string
              example:
                - "000373"
                - "L25003"
            stayLocations:
              type: array
              description: Accommodation geo location codes
              items:
                type: string
              example:
                - "000691"
                - HRV
            ships:
              type: array
              description: Ship codes
              items:
                type: string
              example:
                - "150012"
                - "150013"
            departurePoints:
              type: array
              description: Departure points/airport/port codes
              items:
                $ref: "#/components/schemas/Point"
              example:
                - code: LGW
                  type: AIRPORT
            date:
              type: string
              description: Departure date
              pattern: '^\d{4}-\d{2}-\d{2}$'
              example: 2024-07-01
            boardBasis:
              type: array
              description: Board basis codes
              items:
                type: string
              example:
                - "AI"
                - "PI"
            price:
              type: object
              description: Selected price
              required:
                - level
                - type
                - value
              properties:
                level:
                  $ref: "#/components/schemas/PriceLevel"
                type:
                  $ref: "#/components/schemas/PriceType"
                value:
                  type: number
                  example: 1500
        sortId:
          title: Sorting the search responsse
          description: Lists all available sort id.cruiseDateAscending is the default
          type: string
          enum:
            - DATE_ASCENDING
            - DATE_DESCENDING
            - PRICE_ASCENDING
            - PRICE_DESCENDING
      additionalProperties: false
    CruiseFlightVariantRequest:
      type: object
      required:
        - metaInformation
        - departureAirports
        - offer
      properties:
        metaInformation:
          $ref: "#/components/schemas/MetaInformation"
        departureAirports:
          $ref: "#/components/schemas/Airports"
          description: Departure airports to get the alternate flights including the selected package departure airport.
        offer:
          $ref: "#/components/schemas/CruiseOfferRequest"
      additionalProperties: false
    CruiseUniqueRequest:
      type: object
      required:
        - metaInformation
        - offer
      properties:
        metaInformation:
          $ref: "#/components/schemas/MetaInformation"
        offer:
          $ref: "#/components/schemas/CruiseOfferRequest"
      additionalProperties: false
    CruiseStayOfferRequest:
      type: object
      required:
        - metaInformation
        - offer
      properties:
        metaInformation:
          $ref: "#/components/schemas/MetaInformation"
        offer:
          $ref: "#/components/schemas/CruiseOfferRequestV2"
      additionalProperties: false
    CruiseOfferRequest:
      type: object
      required:
        - type
        - cruise
        - travellers
      properties:
        type:
          $ref: "#/components/schemas/CruiseType"
        offerGroup:
          $ref: "#/components/schemas/OfferGroupRequest"
          description: The offer group is applicable only for the offer type  FLY_CRUISEANDSTAY, FLY_STAYANDCRUISE and FLY_BACKTOBACK
        cruise:
          $ref: "#/components/schemas/CruiseRequest"
        stay:
          $ref: "#/components/schemas/StayRequest"
        flight:
          type: array
          items:
            $ref: "#/components/schemas/FlightRequest"
        travellers:
          type: array
          items:
            $ref: "#/components/schemas/Traveller"
      additionalProperties: false
    CruiseOfferRequestV2:
      type: object
      required:
        - type
        - cruise
        - stay
        - flight
        - travellers
      properties:
        type:
          $ref: "#/components/schemas/CruiseType"
        offerGroup:
          $ref: "#/components/schemas/OfferGroupRequest"
          description: The offer group is applicable only for the offer type  FLY_CRUISEANDSTAY, FLY_STAYANDCRUISE and FLY_BACKTOBACK
        cruise:
          $ref: "#/components/schemas/CruiseRequest"
        stay:
          $ref: "#/components/schemas/StayRequest"
        flight:
          type: array
          items:
            $ref: "#/components/schemas/FlightRequest"
        travellers:
          type: array
          items:
            $ref: "#/components/schemas/Traveller"
      additionalProperties: false
    CruiseAlternateCabinAndBoardOffers:
      title: Cruise alternate cabin and board offers
      type: object
      properties:
        type:
          $ref: "#/components/schemas/CruiseType"
        offerGroup:
          $ref: "#/components/schemas/OfferGroup"
          description: The offer group is applicable only for the offer type  FLY_CRUISEANDSTAY, FLY_STAYANDCRUISE and FLY_BACKTOBACK
        cruise:
          $ref: "#/components/schemas/CruiseV2"
        stay:
          type: array
          items:
            $ref: "#/components/schemas/StayResponse"
        flights:
          type: array
          items:
            $ref: "#/components/schemas/FlightResponse"
          additionalProperties: false
        extras:
          type: array
          items:
            $ref: "#/components/schemas/Extras"
    CruiseStayUpsellOfferRequest:
      type: object
      required:
        - metaInformation
        - offer
      properties:
        metaInformation:
          $ref: "#/components/schemas/MetaInformation"
        offer:
          $ref: "#/components/schemas/CruiseStayUpsellRequest"
        alternateStayDurations: 
          description: Used to send the required alt stay duration data
          type: array
          items:
            type: integer
    CruiseStayUpsellRequest:
      type: object
      required:
        - type
        - cruise
        - travellers
      properties:
        type:
          $ref: "#/components/schemas/CruiseType"
        offerGroup:
          $ref: "#/components/schemas/OfferGroupRequest"
          description: The offer group is applicable only for the offer type  FLY_CRUISEANDSTAY, FLY_STAYANDCRUISE and FLY_BACKTOBACK
        cruise:
          $ref: "#/components/schemas/CruiseRequest"
        stay:
          $ref: "#/components/schemas/StayRequest"
        flight:
          type: array
          items:
            $ref: "#/components/schemas/FlightRequest"
        travellers:
          type: array
          items:
            $ref: "#/components/schemas/Traveller"
      additionalProperties: false
    MetaInformation:
      title: MetaInformation
      description: Details of requester who wants to use this API
      required:
        - locale
        - market
        - brand
        - channel
        - medium
        - currency
      type: object
      properties:
        locale:
          type: string
          example: en_GB
        market:
          type: string
          example: GB
        brand:
          type: string
          example: MARELLA_UK
        channel:
          type: string
          example: B2B
        medium:
          type: string
          example: WEB
        agent:
          type: string
          example: "T|MARCR"
          description: "Agent identifier in format T|XXXX where XXXX is the agent code. Examples include: T|MARCR, T|J0332, T|RIVER"
        currency:
          type: string
          example: GBP
      additionalProperties: false
    Destinations:
      title: List of cruise areas or itnierary ids
      type: array
      minItems: 0
      maxItems: 20
      items:
        type: object
        required:
          - id
          - type
        properties:
          id:
            type: string
            pattern: ^[A-Za-z0-9]+$
            example: "101290"
            description:
              The cruise areas are specific region and has multiple itineraries sailing.
              For example - L34381 cruise area has the 101426, 101425 and 101436 itineraries
          type:
            type: string
            enum:
              - ITINERARY
              - CRUISEAREA
              - COUNTRY
        additionalProperties: false
    CruiseRequest:
      type: object
      required:
        - id
        - duration
        - sailingDate
        - sailing
      properties:
        id:
          type: string
          description: Cruise Id
        duration:
          title: Cruise sailing duration in number of nights
          type: integer
          format: int32
          example: 7
        sailingDate:
          type: string
          description: Cruise sailing start date. Stay start date for STAYBEFORECRUISE
          example: "2024-12-25"
        sailing:
          type: array
          items:
            type: object
            required:
              - id
              - sourceCode
              - itinerary
              - departurePoint
              - arrivalPoint
              - cabinBoard
            properties:
              id:
                type: string
                example: XXXX0005/119
              sourceCode:
                type: string
                example: XXXX0029/011
                description: Atcom cruise code
              itinerary:
                $ref: "#/components/schemas/Itinerary"
              departurePoint:
                $ref: "#/components/schemas/Point"
              arrivalPoint:
                $ref: "#/components/schemas/Point"
              cabinBoard:
                type: array
                items:
                  type: object
                  required:
                    - cabinSequenceNumber
                    - cabinType
                    - boardType
                    - travellerIds
                  properties:
                    cabinSequenceNumber:
                      type: integer
                      description: Cabin sequence number start from 1 and increments by 1
                      minimum: 1
                      maximum: 5
                      format: int32
                      example: 1
                    cabinType:
                      type: string
                      example: ZI01
                    boardType:
                      type: string
                      example: AI
                    travellerIds:
                      type: array
                      items:
                        type: integer
                        format: int32
                      example: [2, 3]
              ship:
                $ref: "#/components/schemas/Ship"
    StayRequest:
      type: object
      required:
        - id
        - code
        - sourceCode
        - duration
        - roomBoard
      properties:
        id:
          type: string
          example: 1176987100/3
        code:
          type: string
          example: "9929"
        sourceCode:
          type: string
          example: ESMJ0004
        duration:
          $ref: "#/components/schemas/StayDuration"
        roomBoard:
          type: array
          items:
            type: object
            required:
              - roomSequenceNumber
              - roomType
              - boardType
              - travellerIds
            properties:
              roomSequenceNumber:
                type: integer
                description: Cabin sequence number start from 1 and increments by 1
                minimum: 1
                maximum: 5
                format: int32
                example: 1
              roomType:
                type: string
                example: ZI01
              boardType:
                type: string
                example: AI
              travellerIds:
                type: array
                items:
                  type: integer
                  format: int32
                example: [2, 3]
    StayDuration:
      title: Stay Duration
      type: object
      required:
        - numberOfNights
        - stayOrder
      properties:
        numberOfNights:
          title: Number of nights
          type: integer
          format: int32
          example: 5
          description: Number of nights stay in before or after cruise
        stayOrder:
          title: Stay order
          type: string
          enum:
            - STAYAFTERCRUISE
            - STAYBEFORECRUISE
          description: The stay order before or after cruise
      additionalProperties: false
      description: Stay is available only for the 7 days cruise sailing duration
    FlightRequest:
      type: object
      required:
        - id
        - routeCode
        - directions
      properties:
        id:
          type: string
          example: 4461763247/5111314
        routeCode:
          type: string
          example: PMILTN6ALTNPMI
        directions:
          type: array
          items:
            type: object
            required:
              - id
              - direction
              - segments
            properties:
              id:
                type: string
                example: "1"
              direction:
                $ref: "#/components/schemas/DirectionType"
                example: OUTBOUND
              segments:
                type: array
                items:
                  type: object
                  required:
                    - id
                    - departureAirport
                  properties:
                    id:
                      type: string
                      example: "1"
                    departureAirport:
                      type: string
                      example: LGW
    Filter:
      title: F

# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tui-group/refs/heads/main/openapi/tui-group-tui-cruise-price-and-availability-openapi.yml