Amadeus Solutions Shopping API

openapi: 3.2.0
info:
  version: 1.2.0
  title: Branded Fares Upsell Display SeatMaps Shopping API
  x-tags:
  - '#quick-connect'
  - '#online-retail'
  - '#mobile-services'
  - '#ama-for-dev'
  x-status: validated
  x-release-note:
    1.2.0:
    - Add chargeableSeat element
    - Add lastTicketingDateTime
    1.1.0:
    - Add Margins and Discounts content from Margin Manager product - **only available in Enterprise**
    1.0.0:
    - First version of Branded Fares Upsell
  description: "\nBefore using this API, we recommend you read our **[Authorization Guide](https://developers.amadeus.com/self-service/apis-docs/guides/authorization-262)** for more information on how to generate an access token. \n\nPlease also be aware that our test environment is based on a subset of the production, if you are not returning any results try with big cities/airports like LON (London) or NYC (New-York)."
servers:
- url: https://test.api.amadeus.com/v1
tags:
- name: Shopping
paths:
  /shopping/flight-offers/upselling:
    post:
      tags:
      - Shopping
      operationId: upsellAirOffers
      summary: Amadeus Return a List of Upsell Flight Offers Based on Given Flight Offers
      parameters:
      - $ref: '#/components/parameters/getOverride'
      responses:
        '200':
          $ref: '#/components/responses/returnUpsell'
        '400':
          $ref: '#/components/responses/400_Upsell'
        default:
          $ref: '#/components/responses/500'
      description: ''
      requestBody:
        content:
          application/vnd.amadeus+json:
            schema:
              title: Get_Upsell_Query
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/FlightOfferUpsellIn'
              example:
                data:
                  type: flight-offers-upselling
                  flightOffers:
                  - type: flight-offer
                    id: '1'
                    source: GDS
                    instantTicketingRequired: false
                    nonHomogeneous: false
                    oneWay: false
                    lastTicketingDate: '2021-07-04'
                    numberOfBookableSeats: 2
                    itineraries:
                    - duration: PT2H5M
                      segments:
                      - departure:
                          iataCode: CDG
                          terminal: 2F
                          at: '2021-07-04T09:30:00'
                        arrival:
                          iataCode: MAD
                          terminal: '2'
                          at: '2021-07-04T11:35:00'
                        carrierCode: AF
                        number: '1300'
                        aircraft:
                          code: '321'
                        operating:
                          carrierCode: AF
                        duration: PT2H5M
                        id: '2'
                        numberOfStops: 0
                        blacklistedInEU: false
                    - duration: PT1H55M
                      segments:
                      - departure:
                          iataCode: MAD
                          terminal: '2'
                          at: '2021-07-11T18:35:00'
                        arrival:
                          iataCode: ORY
                          terminal: '1'
                          at: '2021-07-11T20:30:00'
                        carrierCode: AF
                        number: '9433'
                        aircraft:
                          code: '318'
                        operating:
                          carrierCode: AF
                        duration: PT1H55M
                        id: '14'
                        numberOfStops: 0
                        blacklistedInEU: false
                    price:
                      currency: EUR
                      total: '410.86'
                      base: '240.00'
                      fees:
                      - amount: '0.00'
                        type: SUPPLIER
                      - amount: '0.00'
                        type: TICKETING
                      grandTotal: '410.86'
                      additionalServices:
                      - amount: '60.00'
                        type: CHECKED_BAGS
                    pricingOptions:
                      fareType:
                      - PUBLISHED
                      includedCheckedBagsOnly: false
                    validatingAirlineCodes:
                    - AF
                    travelerPricings:
                    - travelerId: '1'
                      fareOption: STANDARD
                      travelerType: ADULT
                      price:
                        currency: EUR
                        total: '201.96'
                        base: '126.00'
                      fareDetailsBySegment:
                      - segmentId: '2'
                        cabin: ECONOMY
                        fareBasis: AS50OALG
                        brandedFare: LIGHT1
                        class: A
                        includedCheckedBags:
                          quantity: 0
                      - segmentId: '14'
                        cabin: ECONOMY
                        fareBasis: VS50OALG
                        brandedFare: LIGHT1
                        class: V
                        includedCheckedBags:
                          quantity: 0
                    - travelerId: '2'
                      fareOption: STANDARD
                      travelerType: CHILD
                      price:
                        currency: EUR
                        total: '176.96'
                        base: '101.00'
                      fareDetailsBySegment:
                      - segmentId: '2'
                        cabin: ECONOMY
                        fareBasis: AS50OALG
                        brandedFare: LIGHT1
                        class: A
                      - segmentId: '14'
                        cabin: ECONOMY
                        fareBasis: VS50OALG
                        brandedFare: LIGHT1
                        class: V
                    - travelerId: '3'
                      fareOption: STANDARD
                      travelerType: HELD_INFANT
                      associatedAdultId: '1'
                      price:
                        currency: EUR
                        total: '31.94'
                        base: '13.00'
                      fareDetailsBySegment:
                      - segmentId: '2'
                        cabin: ECONOMY
                        fareBasis: AS50OALG
                        brandedFare: LIGHT1
                        class: A
                      - segmentId: '14'
                        cabin: ECONOMY
                        fareBasis: VS50OALG
                        brandedFare: LIGHT1
                        class: V
                    fareRules:
                      rules:
                      - category: EXCHANGE
                        maxPenaltyAmount: '0.00'
                      - category: REVALIDATION
                        notApplicable: true
                  payments:
                  - brand: VISA_IXARIS
                    binNumber: 123456
                    flightOfferIds:
                    - 1
        description: list of criteria to upsell a dedicated flight-offers
        required: true
  /shopping/flight-offers/pricing:
    post:
      tags:
      - Shopping
      operationId: quoteAirOffers
      summary: Amadeus Confirm Pricing of Given FlightOffers.
      parameters:
      - $ref: '#/components/parameters/getOverride'
      - name: include
        description: "Sub-resources to be included:\n * **credit-card-fees** to get the credit card fee applied on the booking\n * **bags** to get extra bag options\n * **other-services** to get services options\n * **detailed-fare-rules** to get detailed fare rules options\n"
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - credit-card-fees
            - bags
            - other-services
            - detailed-fare-rules
      - name: forceClass
        description: 'parameter to force the usage of booking class for pricing

          - **true**, to for pricing with the specified booking class

          - **false**, to get the best available price

          '
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          $ref: '#/components/responses/returnQuotation'
        '400':
          $ref: '#/components/responses/400_Prices'
        default:
          $ref: '#/components/responses/500'
      description: ''
      requestBody:
        content:
          application/vnd.amadeus+json:
            schema:
              title: Get_Price_Query
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/FlightOfferPricingIn'
              example:
                data:
                  type: flight-offers-pricing
                  flightOffers:
                  - type: flight-offer
                    id: '1'
                    source: GDS
                    instantTicketingRequired: false
                    nonHomogeneous: false
                    oneWay: false
                    lastTicketingDate: '2020-08-04'
                    numberOfBookableSeats: 9
                    itineraries:
                    - duration: PT32H15M
                      segments:
                      - departure:
                          iataCode: SYD
                          terminal: '1'
                          at: '2021-02-01T19:15:00'
                        arrival:
                          iataCode: SIN
                          terminal: '1'
                          at: '2021-02-02T00:30:00'
                        carrierCode: TR
                        number: '13'
                        aircraft:
                          code: '789'
                        operating:
                          carrierCode: TR
                        duration: PT8H15M
                        id: '1'
                        numberOfStops: 0
                        blacklistedInEU: false
                      - departure:
                          iataCode: SIN
                          terminal: '1'
                          at: '2021-02-02T22:05:00'
                        arrival:
                          iataCode: DMK
                          terminal: '1'
                          at: '2021-02-02T23:30:00'
                        carrierCode: TR
                        number: '868'
                        aircraft:
                          code: '788'
                        operating:
                          carrierCode: TR
                        duration: PT2H25M
                        id: '2'
                        numberOfStops: 0
                        blacklistedInEU: false
                    - duration: PT15H
                      segments:
                      - departure:
                          iataCode: DMK
                          terminal: '1'
                          at: '2021-02-05T23:15:00'
                        arrival:
                          iataCode: SIN
                          terminal: '1'
                          at: '2021-02-06T02:50:00'
                        carrierCode: TR
                        number: '867'
                        aircraft:
                          code: '788'
                        operating:
                          carrierCode: TR
                        duration: PT2H35M
                        id: '5'
                        numberOfStops: 0
                        blacklistedInEU: false
                      - departure:
                          iataCode: SIN
                          terminal: '1'
                          at: '2021-02-06T06:55:00'
                        arrival:
                          iataCode: SYD
                          terminal: '1'
                          at: '2021-02-06T18:15:00'
                        carrierCode: TR
                        number: '12'
                        aircraft:
                          code: '789'
                        operating:
                          carrierCode: TR
                        duration: PT8H20M
                        id: '6'
                        numberOfStops: 0
                        blacklistedInEU: false
                    price:
                      currency: EUR
                      total: '546.70'
                      base: '334.00'
                      fees:
                      - amount: '0.00'
                        type: SUPPLIER
                      - amount: '0.00'
                        type: TICKETING
                      grandTotal: '546.70'
                    pricingOptions:
                      fareType:
                      - PUBLISHED
                      includedCheckedBagsOnly: true
                    validatingAirlineCodes:
                    - HR
                    travelerPricings:
                    - travelerId: '1'
                      fareOption: STANDARD
                      travelerType: ADULT
                      price:
                        currency: EUR
                        total: '546.70'
                        base: '334.00'
                      fareDetailsBySegment:
                      - segmentId: '1'
                        cabin: ECONOMY
                        fareBasis: O2TR24
                        class: O
                        includedCheckedBags:
                          weight: 20
                          weightUnit: KG
                      - segmentId: '2'
                        cabin: ECONOMY
                        fareBasis: O2TR24
                        class: O
                        includedCheckedBags:
                          weight: 20
                          weightUnit: KG
                      - segmentId: '5'
                        cabin: ECONOMY
                        fareBasis: X2TR24
                        class: X
                        includedCheckedBags:
                          weight: 20
                          weightUnit: KG
                      - segmentId: '6'
                        cabin: ECONOMY
                        fareBasis: H2TR24
                        class: H
                        includedCheckedBags:
                          weight: 20
                          weightUnit: KG
        description: list of criteria to confirm the price of a dedicated flight-offers
        required: true
  /shopping/flight-offers:
    post:
      tags:
      - Shopping
      operationId: searchFlightOffers
      summary: Amadeus Return List of Flight Offers Based on Posted Searching Criteria.
      parameters:
      - $ref: '#/components/parameters/getOverride'
      responses:
        '200':
          $ref: '#/components/responses/returnAirOffers'
        '400':
          $ref: '#/components/responses/400_Search'
        default:
          $ref: '#/components/responses/500'
      description: ''
      requestBody:
        content:
          application/vnd.amadeus+json:
            schema:
              $ref: '#/components/schemas/GetFlightOffersQuery'
        description: list of criteria to retrieve a list of flight offers
        required: true
    get:
      tags:
      - Shopping
      operationId: getFlightOffers
      summary: Amadeus Return List of Flight Offers Based on Searching Criteria.
      parameters:
      - name: originLocationCode
        in: query
        description: city/airport [IATA code](http://www.iata.org/publications/Pages/code-search.aspx) from which the traveler will depart, e.g. BOS for Boston
        required: true
        x-example: SYD
        schema:
          type: string
          pattern: '[A-Z]{3}'
      - name: destinationLocationCode
        in: query
        description: city/airport [IATA code](http://www.iata.org/publications/Pages/code-search.aspx) to which the traveler is going, e.g. PAR for Paris
        required: true
        x-example: BKK
        schema:
          type: string
          pattern: '[A-Z]{3}'
      - name: departureDate
        in: query
        description: the date on which the traveler will depart from the origin to go to the destination. Dates are specified in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) YYYY-MM-DD format, e.g. 2017-12-25
        required: true
        x-example: '2023-05-02'
        schema:
          type: string
          format: date
      - name: returnDate
        in: query
        description: the date on which the traveler will depart from the destination to return to the origin. If this parameter is not specified, only one-way itineraries are found. If this parameter is specified, only round-trip itineraries are found. Dates are specified in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) YYYY-MM-DD format, e.g. 2018-02-28
        required: false
        schema:
          type: string
          format: date
      - name: adults
        in: query
        description: 'the number of adult travelers (age 12 or older on date of departure).


          The total number of seated travelers (adult and children) can not exceed 9.'
        required: true
        schema:
          type: integer
          default: 1
          maximum: 9
          minimum: 1
      - name: children
        in: query
        description: 'the number of child travelers (older than age 2 and younger than age 12 on date of departure) who will each have their own separate seat. If specified, this number should be greater than or equal to 0


          The total number of seated travelers (adult and children) can not exceed 9.'
        required: false
        schema:
          type: integer
          maximum: 9
          minimum: 0
      - name: infants
        in: query
        description: the number of infant travelers (whose age is less or equal to 2 on date of departure). Infants travel on the lap of an adult traveler, and thus the number of infants must not exceed the number of adults. If specified, this number should be greater than or equal to 0
        required: false
        schema:
          type: integer
          maximum: 9
          minimum: 0
      - name: travelClass
        in: query
        description: most of the flight time should be spent in a cabin of this quality or higher. The accepted travel class is economy, premium economy, business or first class. If no travel class is specified, the search considers any travel class
        required: false
        schema:
          type: string
          enum:
          - ECONOMY
          - PREMIUM_ECONOMY
          - BUSINESS
          - FIRST
      - name: includedAirlineCodes
        in: query
        description: 'This option ensures that the system will only consider these airlines. This can not be cumulated with parameter excludedAirlineCodes.


          Airlines are specified as [IATA airline codes](http://www.iata.org/publications/Pages/code-search.aspx) and are comma-separated, e.g. 6X,7X,8X

          '
        required: false
        style: form
        explode: false
        schema:
          type: string
          pattern: '[0-9A-Z]{2}'
      - name: excludedAirlineCodes
        in: query
        description: 'This option ensures that the system will ignore these airlines. This can not be cumulated with parameter includedAirlineCodes.


          Airlines are specified as [IATA airline codes](http://www.iata.org/publications/Pages/code-search.aspx) and are comma-separated, e.g. 6X,7X,8X

          '
        required: false
        style: form
        explode: false
        schema:
          type: string
          pattern: '[0-9A-Z]{2}'
      - name: nonStop
        in: query
        description: if set to true, the search will find only flights going from the origin to the destination with no stop in between
        required: false
        schema:
          type: boolean
          default: false
      - name: currencyCode
        in: query
        description: the preferred currency for the flight offers. Currency is specified in the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format, e.g. EUR for Euro
        required: false
        schema:
          type: string
          pattern: '[A-Z]{3}'
      - name: maxPrice
        in: query
        description: maximum price per traveler. By default, no limit is applied. If specified, the value should be a positive number with no decimals
        required: false
        schema:
          type: integer
          minimum: 1
      - name: max
        in: query
        description: maximum number of flight offers to return. If specified, the value should be greater than or equal to 1
        required: false
        schema:
          type: integer
          default: 250
          minimum: 1
      responses:
        '200':
          $ref: '#/components/responses/GETAirOffersReply'
        '400':
          $ref: '#/components/responses/400_Search'
        default:
          $ref: '#/components/responses/500'
      description: ''
components:
  schemas:
    Error_400_2:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Issue_2'
      required:
      - errors
      example:
        errors:
        - status: 400
          code: 477
          title: INVALID FORMAT
          detail: invalid query parameter format
          source:
            parameter: airport
            example: CDG
    OriginalFlightStop:
      description: details of stops for direct or change of gauge flights
      type: object
      properties:
        iataCode:
          description: '[IATA airline codes](http://www.iata.org/publications/Pages/code-search.aspx)'
          type: string
          example: JFK
        duration:
          type: string
          description: stop duration in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) PnYnMnDTnHnMnS format, e.g. PT2H10M
          example: PT2H10M
    PricingOptionsFareType:
      type: array
      description: type of fare of the flight-offer
      items:
        type: string
        enum:
        - PUBLISHED
        - NEGOTIATED
        - CORPORATE
      example:
      - PUBLISHED
    PhoneDeviceType:
      type: string
      description: Type of the device (Landline, Mobile or Fax)
      enum:
      - MOBILE
      - LANDLINE
      - FAX
    Extended_CabinRestriction:
      allOf:
      - $ref: '#/components/schemas/CabinRestriction'
      - type: object
        properties:
          coverage:
            $ref: '#/components/schemas/Coverage'
    Stakeholder:
      type: object
      description: stakeholder definition
      properties:
        id:
          description: item identifier
          type: string
        dateOfBirth:
          type: string
          format: date
          description: The date of birth in ISO 8601 format (yyyy-mm-dd)
        gender:
          $ref: '#/components/schemas/StakeholderGender'
        name:
          $ref: '#/components/schemas/Name'
        documents:
          type: array
          description: Advanced Passenger Information - regulatory identity documents - SSR DOCS & DOCO elements
          items:
            $ref: '#/components/schemas/IdentityDocument'
    Collection_Meta_Upsell:
      title: Collection_Meta
      properties:
        count:
          type: integer
          example: 1
        oneWayUpselledCombinations:
          type: array
          items:
            title: oneWayUpselledCombinations
            properties:
              flightOfferId:
                type: string
              upselledFlightOfferIds:
                type: array
                items:
                  type: string
    DateTimeType:
      type: object
      properties:
        date:
          description: Dates are specified in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) YYYY-MM-DD format, e.g. 2018-12-25
          type: string
          format: date
          example: '2018-09-22'
        time:
          description: Local time. hh:mm:ss format, e.g 10:30:00
          type: string
          example: '10:30:00'
      required:
      - date
    ChargeableSeat:
      description: Details of chargeable seat
      type: object
      properties:
        id:
          description: Id of the chargeable seat
          type: string
          example: '1'
        number:
          type: string
          description: seat number
          example: 33D
          pattern: '[1-9][0-9]{0,2}[A-Z]?'
    FlightOfferPricingOut:
      title: FlightOfferPricing-Output
      type: object
      description: priced flight Offers and conditions
      required:
      - type
      - flightOffers
      properties:
        type:
          description: the resource name
          type: string
          example: flight-offer-pricing
        flightOffers:
          description: list of flight offer to price
          type: array
          minItems: 1
          maxItems: 6
          items:
            $ref: '#/components/schemas/FlightOffer'
        bookingRequirements:
          type: object
          title: BookingRequirements
          description: pricing condition at booking level
          properties:
            invoiceAddressRequired:
              type: boolean
              description: If true, an invoice address is required for the creation of the flight-order
              example: true
            mailingAddressRequired:
              type: boolean
              description: If true, a postal address is required for the creation of the flight-order
              example: true
            emailAddressRequired:
              type: boolean
              description: If true, an email address is required for the creation of the flight-order
              example: true
            phoneCountryCodeRequired:
              type: boolean
              description: If true, the phone country code (e.g. '33') associated for each phone number is required for the creation of the flight-order
              example: true
            mobilePhoneNumberRequired:
              type: boolean
              description: If true, a mobile phone number is required for the creation of the flight-order
              example: true
            phoneNumberRequired:
              type: boolean
              description: If true, a phone number is required for the creation of the flight-order
              example: true
            postalCodeRequired:
              type: boolean
              description: If true, a postal code is required for the creation of the flight-order
              example: true
            travelerRequirements:
              type: array
              description: traveler pricing condition
              items:
                title: PassengerConditions
                properties:
                  travelerId:
                    type: string
                    description: Id of the traveler
                    example: 1
                  genderRequired:
                    type: boolean
                    description: If true, the gender is required for the concerned traveler for the creation of the flight-order
                    example: true
                  documentRequired:
                    type: boolean
                    description: If true, a document is required for the concerned traveler for the creation of the flight-order
                    example: true
                  documentIssuanceCityRequired:
                    type: boolean
                    description: If true, the isuance city of the document is required for the concerned traveler for the creation of the flight-order
                    example: true
                  dateOfBirthRequired:
                    type: boolean
                    description: If true, the date of bitrth is required for the concerned traveler for the creation of the flight-order
                    example: true
                  redressRequiredIfAny:
                    type: boolean
                    description: If true, the redress is required if any for the concerned traveler for the creation of the flight-order
                    example: true
                  airFranceDiscountRequired:
                    type: boolean
                    description: If true, the Air France discount is required for the concerned traveler for the creation of the flight-order
                    example: false
                  spanishResidentDiscountRequired:
                    type: boolean
                    description: If true, the Spanish resident discount is required for the concerned traveler for the creation of the flight-order
                    example: false
                  residenceRequired:
                    type: boolean
                    description: If true, the address is required for the concerned traveler for the creation of the flight-order
                    example: true
    DetailedFareRules:
      title: detailedFareRules
      type: object
      properties:
        fareBasis:
          type: string
          example: VRDFR9
        name:
          type: string
        fareNotes:
          $ref: '#/components/schemas/TermAndCondition'
        segmentId:
          description: Id of the segment concerned by the fare rule
          type: string
          example: '1'
    ConnectionRestriction:
      description: Restriction towards number of connections.
      type: object
      properties:
        maxNumberOfConnections:
          description: The maximal number of connections for each itinerary. Value can be 0, 1 or 2.
          type: number
          example: 2
        nonStopPreferred:
          description: When this option is requested, recommendations made of Non-Stop flights only are favoured by the search, on the whole itinerary, with a weight of 75%.
          type: boolean
          example: false
        airportChangeAllowed:
          description: Allow to change airport during connection
          type: boolean
          example: false
        technicalStopsAllowed:
          description: This option allows the single segment to have one or more intermediate stops (technical stops).
          type: boolean
          example: true
    Traveler:
      title: traveler element
      description: the traveler of the trip
      allOf:
      - $ref: '#/components/schemas/Stakeholder'
      - type: object
        properties:
          emergencyContact:
            description: emergency contact
            $ref: '#/components/schemas/EmergencyContact'
          loyaltyPrograms:
            description: list of loyalty program followed by the traveler
            type: array
            minItems: 0
            maxItems: 10
            items:
              $ref: '#/components/schemas/LoyaltyProgram'
          discountEligibility:
            description: list of element that allow a discount.
            type: array
            minItems: 0
            maxItems: 10
            items:
              $ref: '#/components/schemas/Discount'
          contact:
            $ref: '#/components/schemas/Contact'
    TravelClass:
      description: quality of service offered in the cabin where the seat is located in this flight. Economy, premium economy, business or first class
      type: string
      enum:
      - ECONOMY
      - PREMIUM_ECONOMY
      - BUSINESS
      - FIRST
      example: PREMIUM_ECONOMY
    FlightFilters:
      type: object
      properties:
        crossBorderAllowed:
          description: Allows to search a location outside the borders when a radius around a location is specified. Default is false.
          type: boolean
          example: false
        moreOvernightsAllowed:
          description: This flag enables/disables the possibility to have more overnight flights in Low Fare Search
          type: boolean
          example: false
        returnToDepartureAirport:
          description: This option force to retrieve flight-offer with a departure and a return in the same airport
          type: boolean
          example: false
        railSegmentAllowed:
          description: This flag enable/disable filtering of rail segment (TGV AIR, RAIL ...)
          type: boolean
          example: true
        busSegmentAllowed:
          description: This flag enable/disable filtering of bus segment
          type: boolean
          example: true
        maxFlightTime:
          description: Maximum flight time as a percent

# --- truncated at 32 KB (182 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amadeus-solutions/refs/heads/main/openapi/amadeus-solutions-shopping-api-openapi.yml