Trip Ninja Pricing & Booking API

openapi: "3.0.0"

info:
  version: "4.15.0"
  title: Trip Ninja Endpoint Documentation
  description: |
    <h2>Introduction</h2>
    Trip Ninja uses a REST API with requests and responses in JSON format. For development and testing, the pre-production servers
    are to be used. Once ready for live use, access to the production servers will be provided. All search endpoints have both production
    and pre-production endpoints - these correspond to the Data Source’s production and pre-production services, and can be used as desired.<br  />
    <h2>Trip Ninja API URLs</h2>

    Pre-Production: https://preprodapi.tripninja.io

    For security, Trip Ninja’s servers are only accessible from whitelisted IPs. Please contact your account manager to whitelist IPs you
    will be using.

    Before you start ensure that:<br  />
        - IP addresses have been provided to be whitelisted for our servers.<br  />
        - PCC / OfficeID emulation via Trip Ninja’s PCC/OfficeID has been set up.<br  />
        - API username and password have been provided by Trip Ninja.<br  />

    <h2>Authentication</h2>
    Trip Ninja uses Basic Authentication standards. Simply encode your username and password string using base64 and pass it in the
    authorization headers. See the python example below on how this is done. In the example, the payload and API endpoint url are not
    shown.

    Python Example:

    <pre>
    import base64
    auth = base64.b64encode("USERNAME:PASSWORD")
    headers = {
        'authorization': "Basic "+ auth,
    }
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    </pre>

  x-logo:
    url: 'https://s3.amazonaws.com/tn-api-docs/trip_ninja_logo.png'
    altText: Trip Ninja logo

servers:
  - url: https://preprodapi.tripninja.io
    description: Pre-Production server

paths:
    /price/{endpoint}/:
        post:
            parameters:
                - in: path
                  name: endpoint
                  required: true
                  schema:
                      type: string
                      enum: [preprod, prod]
                  description: Parameter toggles Data Source production and pre-production endpoints
            summary: "Price Confirmation"
            description: Once the desired flights have been selected, call the price confirm endpoint to confirm their availability and prices.
            operationId: PriceConfirm
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PriceConfirmRequest'

            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PriceConfirmResponse'
                400:
                    description: Unable to confirm trip pricing
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: IE45
                                    message:
                                        type: string
                                        example: 'itinerary with reference 1 was unsuccessful. reason Invalid date. Check arrival and departure dates'

    /book/list/?agency={agency}&user={agent_email}&offset={offset}&limit={limit}:
        get:
            parameters:
                - in: query
                  name: agency
                  schema:
                      type: string
                  description: >
                    Travel agency id for which to list bookings from. Either this or agent_email should be passed.
                    This parameter is incompatible with `agent_email`.
                  example: '9238812-2131233-ee213123'
                - in: query
                  name: agent_email
                  schema:
                      type: string
                  description: >
                    Email address of the travel agent to list bookings from. Either this or agent_email should be passed.
                    This parameter is incompatible with `agency`.
                  example: agent@travelagency.com
                - in: query
                  name: offset
                  schema:
                    type: integer
                  description: The number of items to skip before starting to collect the result set
                  example: 100
                - in: query
                  name: limit
                  schema:
                    type: integer
                  description: The numbers of items to return
                  example: 10
            summary: "List Bookings"
            description: "Get a list of all bookings for travel agency or agent."
            operationId: "ListBooking"

            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListBookingResponse'
                400:
                    description: Unable to get bookings
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: IE2200
                                    message:
                                        type: string
                                        example: 'Invalid agency/agent entered'

    /book/trip/{super_trip_id}/?agency={agency}:
        get:
            parameters:
                - in: path
                  name: super_trip_id
                  schema:
                      type: string
                  description: A unique key used to identify an entire super trip which incorporates all inclusive bookings (i.e. Cars, Hotels, other Flights). The key can be used to search and price flights again and place them into the same super trip.
                  example: "5df23dd9s72hne223d299err2323423r2342r221"
                - in: query
                  name: agency
                  schema:
                      type: string
                  description: >
                    Travel agency for which to list bookings from. Either this or agent_email should be passed.
                    This parameter is incompatible with `agent_email`.
                  example: tripninja
            summary: "Booking Detail"
            description: "Retrieve a booking details"
            operationId: "BookingDetail"

            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetBookingDetailsResponse'
                400:
                    description: Unable to retrieve booking information
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: IE38
                                    message:
                                        type: string
                                        example: 'Trip ID not found'


    /book/{endpoint}/:
        post:
            parameters:
                - in: path
                  name: endpoint
                  required: true
                  schema:
                      type: string
                      enum: [preprod, prod]
                  description: Parameter toggles Data Source production and pre-production endpoints
            summary: "Create Booking"
            description: "When a trip is to be booked, send a request to the endpoint /book/ to create the Universal Record and associated PNR's for the trip. The booking can then be placed on the agency's ticketing queue."
            operationId: "CreateBooking"
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateBookingRequest'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    super_trip_id:
                                      description: A unique key used to identify an entire super trip which incorporates all inclusive bookings (i.e. Cars, Hotels, Flights).
                                      type: string
                                      required: true
                                      example: "5df23dd9s72hne223d299err2323423r2342r221"
                                    ur_locator_codes:
                                        type: json
                                        description: Map of itinerary_reference and Unique Identifier of a Universal Record.
                                        example: {"1":"D917A841", 2: "8YYE22P0", "3": "8YYE22P0"}
                                    pnr_numbers:
                                        type: json
                                        description: Map of itinerary_reference and PNR number of a booking. For consolidated tickets the PCC of the data source will be the key.
                                        example: {"1":"TH2H52", "2": "UG22WH", "3": "UG22WH"}
                                    consolidated_tickets:
                                        type: json
                                        description: A breakdown of which itineraries are stored under which PNR.
                                        example: {"HC4C": ["1"], "Y4E5": ["2", "3"]}
                                    booked_hotels:
                                        type: array
                                        description: A list of the hotels booked.
                                        items:
                                          $ref: '#/components/schemas/BookedHotelResponse'
                400:
                    description: Unable to create booking
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: IE46
                                    message:
                                        type: string
                                        example: 'trip has already been booked'

    /book/:
        delete:
            summary: "Cancel Booking"
            description: "To cancel a booking, send a request with the trip_id and ur_locator_code."
            operationId: "CancelBooking"
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CancelRequest'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                  status:
                                    type: string
                                    example: "Success"
                                  message:
                                    type: string
                                    example: "Trip was successfully cancelled"
                400:
                    description: Unable to cancel booking
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: IE38
                                    message:
                                        type: string
                                        example: 'Trip ID not found'
    /queue/:
        post:
            summary: "Add To Ticketing Queue"
            description: If a trip has been booked, but not yet added to the agency ticketing queue, use this endpoint to add it to their queue.
            operationId: AddBookingToTicketingQueue
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AddBookingToTicketingQueueRequest'

            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: "0"
                                    message:
                                      type: string
                                      example: "success"

                400:
                    description: Unable to add trip to ticketing queue
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: IE38
                                    message:
                                        type: string
                                        example: 'Trip ID not found'


    /ticket/:
        post:
            summary: "Ticket"
            description: If a trip has been queued, but not yet ticketed, use this endpoint to do the ticketing.
            operationId: Ticket
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/TicketingRequest'

            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                  status:
                                    type: string
                                    example: "0"
                                  message:
                                    type: string
                                    example: "success"

                400:
                    description: Unable to issue ticket
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    status:
                                        type: string
                                        example: IE45
                                    message:
                                        type: string
                                        example: 'itinerary with reference 1 was unsuccessful. reason LAST TIME TO TICKET IS PAST - PLEASE REPRICE (08SEP20 23:19)'



components:
  schemas:
    frequent_flyer_cards:
      description: The passenger's frequent flyer card details
      type: array
      items:
        type: object
        properties:
          itinerary_reference:
            description: The itinerary reference to apply the card to.
            type: string
            example: "1"
          card_supplier:
            description: The supplier code of the loyalty program supplier.
            type: string
            example: "AA"
          card_number:
            description: The frequent flyer card number.
            type: string
            example: '84299921292'

    PriceConfirmResponse:
      title: Response
      type: object
      properties:
        super_trip_id:
          description: A unique key used to identify an entire super trip which incorporates all inclusive bookings (i.e. Cars, Hotels, other Flights). The key can be used to search and price flights again and place them into the same super trip.
          type: string
          example: "5df23dd9s72hne223d299err2323423r2342r221"
        trip_id:
            description: A unique key used for identification and when booking a trip.
            type: string
            example: "129a4045ef84edc4c0d5f0b1b28a906495d3f966"
        pricing:
                description: Breakdown of the total confirmed prices including taxes, fees, and markup for the trip.
                type: object
                $ref: '#/components/schemas/trip_pricing_breakdown'
        itinerary:
            $ref: '#/components/schemas/price_confirm_itinerary_response_list'

    GetBookingDetailsResponse:
      title: Response
      type: object
      properties:
        super_trip_id:
          description: A unique key used to identify an entire super trip which incorporates all inclusive bookings (i.e. Cars, Hotels, other Flights). The key can be used to search and price flights again and place them into the same super trip.
          type: string
          example: "5df23dd9s72hne223d299err2323423r2342r221"
        pricing:
          description: Breakdown of the total confirmed prices including taxes, fees, and markup for the trip.
          type: object
          $ref: '#/components/schemas/trip_pricing_breakdown_additional'
        itinerary:
          $ref: '#/components/schemas/itinerary_response_list'
        passengers:
          type: array
          description: All passengers information
          items:
            $ref: '#/components/schemas/passenger_detail'
        hotels:
          type: array
          description: A list of the hotels booked under this super trip.
          items:
            type: object
            description: Hotels
            properties:
              hotel_trace_id:
                type: string
                example: 'ndsf6sjf6sdf7sdf6'
                description: An identifier to refer to the hotel for searching room availability
              status:
                enum: [booked, cancelled]
                description: "Status of the hotel booking"
              booked_hotel_details:
                type: object
                description: The specific details of the booked hotel.
                properties:
                  address:
                    type: object
                    properties:
                      street_address:
                        type: string
                        description: The street address of the hotel.
                        example: '1583 Brunswick St, Halifax, NS B3J 3P5'
                      longitude:
                        type: float
                        description: The longitude of the hotel.
                        example: 44.64511447836071
                      lattitude:
                        type: float
                        description: The lattitude of the hotel.
                        example: -63.575245615440565
                      distance_from_search_reference:
                        type: float
                        description: The distance that the hotel is from the reference submitted in the search.
                        example: 7.5
                      phone_number:
                        type: str
                        description: The contact phone number for the hotel.
                        example: '+1 902-420-0555'
                  hotel_chain:
                    type: string
                    description: The refence for the hotel chain.
                    example: 'GI'
                  hotel_code:
                    type: string
                    description: The reference for the hotel code
                    example: '35573'
                  hotel_name:
                    type: string
                    description: The name of the hotel
                    example: 'Cambridge Suites Hotel Halifax'
                  location_iata:
                    type: string
                    description: The location of the hotel.
                    example: 'LON'
                  check_in_time:
                    type: string
                    description: The check in time for the hotel.
                    example: "3pm"
                  check_out_time:
                    type: string
                    description: The check out time
                    example: "10am"
                  rate_plan_type:
                    type: string
                    example: 'A00BOB'
                    description: The type reference for the rate plan selected for this hotel and this room.
                  total_price:
                    type: number
                    description: Total price of the hotel
                    example: 40.00
                  currency:
                      type: string
                      example: 'CAD'
                      description: Currency the booking was made in.
                  rating:
                      type: int
                      description: The hotel rating
                      example: 4
                  traveller_total:
                      type: int
                      example: 3
                      description: Number of people that will be staying at the hotel.
                  rooms_total:
                      type: int
                      example: 2
                      description: The number of rooms required for the above travellers.




    price_confirm_baggage:
      allOf:
        - $ref: '#/components/schemas/baggage'
      properties:
        additional_checked_bags:
          type: array
          items:
            type: object
            description: Additional Checked Baggage
            properties:
              applicable_bags:
                type: string
                description: Describe which checked bag is this price applicable to
                example: 1stChecked
              base_price:
                type: number
                description: Base price of the checked bag
                example: 40.00
              total_price:
                type: number
                description: Total price of the checked bag
                example: 40.00
              restriction:
                type: string
                description: Information about baggage restrictions
                example: UPTO50LB/23KG AND UPTO62LI/158LCM
              additional_service_reference:
                type: string
                description: Reference for the additional baggage option
                example: C9O
              passenger_reference:
                type: number
                description: The reference for the passenger that the baggage applies to.
                example: 1
        additional_carry_on_bags:
          type: array
          items:
            type: object
            description: Additional Carry On Baggage
            properties:
              applicable_bags:
                type: string
                description: Describe which carry on bag is this price applicable to
                example: 1
              base_price:
                type: number
                description: Base price of the bag
                example: 10.00
              total_price:
                type: number
                description: Total price of the bag
                example: 10.00
              restriction:
                type: string
                description: Information about baggage restrictions
                example: PERSONAL ITEM
              additional_service_reference:
                type: string
                description: Reference for the additional baggage option
                example: C9O
              passenger_reference:
                type: number
                description: The reference for the passenger that the baggage applies to.
                example: 1

    baggage:
        type: object
        description: Details of carryon and checked baggage allowances
        properties:
            applicable_bags:
                type: string
                description:
                example: "1stChecked"
            applicable_carryon_bags:
                type: string
                description:
                example: "1"
            baggage_restrictions:
                type: string
                description:
                example: "UPTO50LB/23KG AND UPTO62LI/158LCM"
            carryon_restrictions:
                type: string
                description:
                example: "CARRYON HAND BAGGAGE ALLOWANCE"


    flight_details:
        type: array
        description: Details of services, meals, terminals for each flight in the segment
        items:
            type: object
            properties:
                flight_number:
                    type: string
                    description: Flight number
                    example: "WS368"
                in_flight_services:
                    type: array
                    description: List of services offered on flight
                    example: ["Entertainment on Demand", "Wi-Fi", "USB Power"]
                meals:
                    type: array
                    description: Details of meals available on flight
                    example: ["FoodForPurchase"]
                origin_terminal:
                    type: string
                    description: Terminal from which the flight departs
                    example: 1
                destination_terminal:
                    type: string
                    description: Terminal at which the flight arrives
                    example: 3
                automated_checkin:
                    type: boolean
                    description:
                    example: false
                on_time_performance:
                    type: string
                    description:
                    example:

    additional_details:
      type: object
      description: Additional Details
      properties:
        e_ticketability:
          type: boolean
          example: true
        latest_ticketing_time:
          type: string
          format: date
          example: "11JUN20"
        refundable:
          type: boolean
          example: true
        cancel_penalty:
          type: object
          description: Information about cancellation
          properties:
            amount:
              type: float
              description: Cancellation penalty amount
              example: 0
            percentage:
              type: float
              description: Cancellation penalty percentage
              example: 100
        change_penalty:
            type: object
            description: Information about changing.
            properties:
              amount:
                type: float
                description: Change penalty amount
                example: 78
              percentage:
                type: float
                description: Change penalty percentage
                example: 0
        fare_types_info:
          type: string
          example: WS3 - Published fare

    trip_pricing_breakdown:
        allOf:
          - $ref: '#/components/schemas/PriceConfirmResponse/properties'
          - type: object
            description: Breakdown of confirmed prices including taxes, fees, and markup for the trip.
            properties:
                confirmed_total_price:
                    type: float
                    description: Total price of the trip after price confirmation (base_fare + taxes + fees). Does not include markup.
                    example: 455.68
                original_total_price:
                    type: float
                    description: Original price of trip from search request - does not include markup.
                    example: 455.61
                base_fare:
                    type: float
                    description: Confirmed base_fare price for the trip.
                    example: 370.04
                taxes:
                    type: float
                    description: Confirmed taxes for the trip.
                    example: 85.64
                fees:
                    type: float
                    description: Confirmed fees for trip *Travelport customers only*
                    example: 0.0
                markup:
                    type: float
                    description: Trip Ninja provided markup amount
                    example: 20.00
                currency:
                    type: string
                    description: Currency in which trip was priced
                    example: USD
                ancillary_total:
                    type: float
                    description: Total of all ancillaries
                    example: 60.00


    trip_pricing_breakdown_additional:
      type: object
      description: Breakdown of confirmed prices including taxes, fees, and markup for the trip.
      properties:
          confirmed_total_price:
              type: float
              description: Total price of the trip after price confirmation (base_fare + taxes + fees). Does not include markup.
              example: 455.68
          original_total_price:
              type: float
              description: Original price of trip from search request - does not include markup.
              example: 455.61
          base_fare:
              type: float
              description: Confirmed base_fare price for the trip.
              example: 370.04
          taxes:
              type: float
              description: Confirmed taxes for the trip.
              example: 85.64
          fees:
              type: float
              description: Confirmed fees for trip *Travelport customers only*
              example: 0.0
          markup:
              type: float
              description: Trip Ninja provided markup amount
              example: 20.00
          currency:
              type: string
              description: Currency in which trip was priced
              example: USD
          additional_markup:
            type: float
            description: Additional markup to be applied to the booking price.
            example: 15.00
          ancillary_total:
            type: float
            description: Total price of all ancillaries.
            example: 30.00

    segment_pricing_breakdown:
        allOf:
          - $ref: '#/components/schemas/PriceConfirmResponse/properties'
          - type: object
            description: Breakdown of confirmed prices including taxes, and fees for the segment.
            properties:
                confirmed_total_price:
                    type: float
                    description: Total price of the segment after price confirmation (base_fare + taxes + fees). Does not include markup.
                    example: 105.68
                original_total_price:
                    type: float
                    description: Original price of segment from search request - does not include markup.
                    example: 100.61
                base_fare:
                    type: float
                    description: Confirmed base_fare price for the segment.
                    example: 70.04
                taxes:
                    type: float
                    description: Confirmed taxes for the segment.
                    example: 30.64
                fees:
                    type: float
                    desc

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webjet/refs/heads/main/openapi/webjet-tripninja-pricing-booking-openapi.yml