Entur Third Party Products by Order API

openapi: 3.2.0
info:
  title: Third Party Product - Partner Third Party Products by Order…
  description: 'Third party product is a catalog for products that does not exist in Enturs standard product database.

    Therefore, third party products must be provided by the client when creating an order. This means third party products are always connected to a specific order line within an order.

    Third party products enable selling products from another marketplace, using Entur''s payment and order apis, which also includes that the sale is settled correctly in Entur''s accounting.'
  version: 2026.09.0
servers:
- url: https://api.entur.io/sales
  description: production
- url: https://api.staging.entur.io/sales
  description: staging
- url: https://api.dev.entur.io/sales
  description: dev
security:
- jwt: []
tags:
- name: Third Party Products by Order
  description: Get third party products for an order
paths:
  /v1/third-party-products/orders/{orderId}:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Third Party Products by Order
      summary: Get third party products for an order
      description: Returns third party products for given orderId
      operationId: getThirdPartyProducts
      parameters:
      - name: orderId
        in: path
        description: The id of the order.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThirdPartyProductsResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
  /v1/third-party-products/orders/{orderId}/order-lines/{orderLineId}:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Third Party Products by Order
      summary: Get specific third party product for an orderLine
      description: Returns third party products for given orderId, orderLineId and orderLineVersion. A Third party product is a product in the system that belongs to an external provider/operator, but is sold or handled through our platform.
      operationId: getThirdPartyProductByOrderLine
      parameters:
      - name: orderId
        in: path
        description: The id of the order.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: orderLineId
        in: path
        description: The id of the order line.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: orderLineVersion
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThirdPartyProduct'
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
components:
  schemas:
    Validity:
      title: Validity period of the product
      required:
      - endOfValidity
      - startOfValidity
      type: object
      properties:
        startOfValidity:
          type: string
          format: date-time
        endOfValidity:
          type: string
          format: date-time
      description: Holds the start and end of validity for the product if this is relevant
    UserProfile:
      title: UserProfile
      required:
      - name
      - userProfileRef
      type: object
      properties:
        userProfileRef:
          $ref: '#/components/schemas/RefType'
        name:
          minItems: 1
          uniqueItems: true
          type: array
          description: A human-readable list of names for the product
          items:
            $ref: '#/components/schemas/TextInLanguage'
        price:
          $ref: '#/components/schemas/PriceWithTax'
        priceContribution:
          $ref: '#/components/schemas/PriceWithTax'
      description: ''
    ThirdPartyProduct:
      required:
      - name
      - orderId
      - orderLineId
      - orderLineVersion
      - orderVersion
      - parameters
      - price
      - priceContribution
      - productRef
      type: object
      properties:
        orderId:
          type: string
          description: The orderId for which the product belongs to.
        orderVersion:
          type: integer
          description: The version of the order for which the product belongs to.
        orderLineId:
          type: string
          description: The orderLineId for which the product belongs to.
        orderLineVersion:
          type: integer
          description: The version of the order line for which the product belongs to.
        productRef:
          $ref: '#/components/schemas/RefType'
        validity:
          $ref: '#/components/schemas/Validity'
        name:
          type: array
          description: A human-readable list of names for the product
          items:
            $ref: '#/components/schemas/TextInLanguage'
        price:
          $ref: '#/components/schemas/PriceWithTax'
        priceContribution:
          $ref: '#/components/schemas/PriceWithTax'
        authorityId:
          type: string
          description: Owner of the product.
        parameters:
          $ref: '#/components/schemas/Parameters'
      description: A third party product for given order and order line.
      examples:
      - orderId: WAYFARE-ORDER-98765
        orderVersion: 1
        orderLineId: WAYFARE-ORDERLINE-2
        orderLineVersion: 1
        productRef:
          id: WAYFARE:ThirdPartyProduct:LuggageReservation
          version: WAYFARE:Version:LuggageReservation-1
        name:
        - lang: eng
          value: Wayfare luggage space reservation
        - lang: nob
          value: Wayfare bagasjeplassreservasjon
        price:
          amount: '59.00'
          taxAmount: '11.80'
          currency: NOK
          taxRate: '25.00'
          taxCode: '03'
        priceContribution:
          amount: '59.00'
          taxAmount: '11.80'
          currency: NOK
          taxRate: '25.00'
          taxCode: '03'
        parameters: {}
        authorityId: WAYFARE:Authority:WAYFARE
    PriceWithTax:
      title: PriceWithTax
      required:
      - amount
      - currency
      - taxAmount
      type: object
      properties:
        amount:
          type: string
          description: Amount including tax amount.
          examples:
          - '399'
        taxAmount:
          type: string
          description: Tax amount
          examples:
          - '36.27'
        taxRate:
          type: string
          description: Tax rate
          examples:
          - '12'
        taxCode:
          type: string
          description: Tax code for this tax rate
          examples:
          - '12'
        currency:
          type: string
          description: Currency
          default: NOK
          examples:
          - NOK
      description: Price with included tax amounts and an optional rate.
    ThirdPartyProductsResponse:
      required:
      - thirdPartyProducts
      type: object
      properties:
        thirdPartyProducts:
          type: array
          items:
            $ref: '#/components/schemas/ThirdPartyProduct'
      description: Response containing third party products.
      examples:
      - thirdPartyProducts:
        - orderId: WAYFARE-ORDER-98765
          orderVersion: 1
          orderLineId: WAYFARE-ORDERLINE-2
          orderLineVersion: 1
          productRef:
            id: WAYFARE:ThirdPartyProduct:LuggageReservation
            version: WAYFARE:Version:LuggageReservation-1
          name:
          - lang: eng
            value: Wayfare luggage space reservation
          - lang: nob
            value: Wayfare bagasjeplassreservasjon
          price:
            amount: '59.00'
            taxAmount: '11.80'
            currency: NOK
            taxRate: '25.00'
            taxCode: '03'
          priceContribution:
            amount: '59.00'
            taxAmount: '11.80'
            currency: NOK
            taxRate: '25.00'
            taxCode: '03'
          parameters: {}
          authorityId: WAYFARE:Authority:WAYFARE
    ApiError:
      required:
      - error
      - exception
      - message
      - path
      - status
      - timestamp
      - title
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
          format: int32
        title:
          type: string
          description: Short, human-readable summary of the problem
        error:
          type: string
        errors:
          type: array
          items:
            type: string
        exception:
          type: string
        message:
          type: string
        path:
          type: string
      examples:
      - timestamp: '2025-01-01T12:00:00Z'
        status: 400
        title: Bad Request
        error: Bad Request
        exception: ValidationException
        message: Validation failed
        path: /v1/third-party-products/XYZ123
    TextInLanguage:
      required:
      - lang
      - value
      type: object
      properties:
        lang:
          type: string
          description: The language of the text
        value:
          type: string
          description: The value of the text in the given language
      description: Contains a text value in a given language
      x-examples:
        example-1:
          lang: nob
          value: Bergen Stasjon
    RefType:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: The identifier to distinguish the product
          examples:
          - ENT:ThirdPartyProduct:MyProduct
        version:
          type: string
          description: Version for the id
          examples:
          - ENT:Version:MyProduct-1
      description: Versioned ID of the product.
    Parameters:
      title: Parameters
      type: object
      properties:
        userProfile:
          $ref: '#/components/schemas/UserProfile'
      description: Similar to OrderLine.fareProducts.parameters, but with additional fields for third party products.
  responses:
    notFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            default:
              value:
                timestamp: '2025-01-01T12:00:00Z'
                status: 404
                title: Not Found
                error: Not Found
                exception: EntityNotFoundException
                message: Entity not found
                path: /v1/third-party-products/XYZ123
    internalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            default:
              value:
                timestamp: '2025-01-01T12:00:00Z'
                status: 500
                title: Internal Server Error
                error: Internal Server Error
                exception: RuntimeException
                message: An unexpected error occurred
                path: /v1/third-party-products/XYZ123
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            default:
              value:
                timestamp: '2025-01-01T12:00:00Z'
                status: 403
                title: Forbidden
                error: Forbidden
                exception: AccessDeniedException
                message: Access denied
                path: /v1/third-party-products/XYZ123
    badRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            default:
              value:
                timestamp: '2025-01-01T12:00:00Z'
                status: 400
                title: Bad Request
                error: Bad Request
                exception: ValidationException
                message: Validation failed
                path: /v1/third-party-products/XYZ123
  parameters:
    ET-Client-Name:
      name: ET-Client-Name
      in: header
      description: 'Entur Client Header.

        It is required that all consumers identify themselves by using this header.

        Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers.

        The structure of ET-Client-Name should be: `<company>-<application>`.'
      required: false
      style: simple
      explode: false
      schema:
        type: string
    X-Correlation-Id:
      name: X-Correlation-Id
      in: header
      description: Correlation id
      required: false
      style: simple
      explode: false
      schema:
        type: string
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT