Entur Reservations API

openapi: 3.2.0
info:
  title: Orders Reservations API
  description: The Order API provides services to create and manage orders in Entur sales platform. It allows clients to create orders, add and change order lines, apply fees, manage connected reservations, and handle traveller information.
  version: 2026.09.0
servers:
- url: https://api.staging.entur.io/sales
  description: Staging test environment
- url: https://api.dev.entur.io/sales
  description: Development test environment
- url: https://api.entur.io/sales
  description: Production environment
security:
- authHeader: []
tags:
- name: Reservations
  description: Services related to reservations on order.
paths:
  /v1/orders/{orderId}/reservations:
    parameters:
    - $ref: '#/components/parameters/dciHeader'
    - $ref: '#/components/parameters/posHeader'
    - $ref: '#/components/parameters/orderIdPathParam'
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    post:
      tags:
      - Reservations
      summary: Add seat Reservation references
      description: Add seat Reservation references to the specified Order. Reservation ID is an UUID
      operationId: addReservationToOrder
      requestBody:
        description: purchasedReservations
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PurchasedReservation'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchasedReservation'
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
  /v1/orders/{orderId}/reservations/{reservationId}:
    parameters:
    - $ref: '#/components/parameters/dciHeader'
    - $ref: '#/components/parameters/posHeader'
    - $ref: '#/components/parameters/orderIdPathParam'
    - name: reservationId
      in: path
      description: Reservation ID associated with Order
      required: true
      style: simple
      explode: false
      schema:
        type: string
        format: uuid
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    put:
      tags:
      - Reservations
      summary: Update seat Reservation reference
      operationId: updateReservationOnOrder
      requestBody:
        description: purchasedReservation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchasedReservation'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchasedReservation'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    delete:
      tags:
      - Reservations
      summary: Remove seat Reservation reference
      operationId: removeReservationFromOrder
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
components:
  parameters:
    orderIdPathParam:
      name: orderId
      in: path
      description: Order ID
      required: true
      style: simple
      explode: false
      schema:
        type: string
    dciHeader:
      name: Entur-Distribution-Channel
      in: header
      description: A header containing the distribution channel ID.
      required: true
      style: simple
      explode: false
      schema:
        type: string
    posHeader:
      name: Entur-Pos
      in: header
      description: Point-of-sale identifier.
      required: true
      style: simple
      explode: false
      schema:
        type: string
    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
  responses:
    notFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    internalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    noContent:
      description: No Content
    conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    badRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    ApiError:
      title: ApiError
      required:
      - error
      - exception
      - message
      - path
      - status
      - timestamp
      - title
      type: object
      properties:
        title:
          type: string
          description: Short, human-readable summary of the problem
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
          format: int32
        error:
          type: string
        exception:
          type: string
        message:
          type: string
        path:
          type: string
      examples:
      - timestamp: '2025-05-13T07:19:30.389Z'
        status: 404
        error: Not Found
        title: Not Found
        exception: NotFoundException
        message: The requested resource was not found.
        path: /orders/ABDC1234
    RefType:
      title: RefType
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: ID of the resources
          examples:
          - ENT:Resource:12345
        version:
          type: string
          description: A specific version of the resource if applicable
          examples:
          - '1'
      description: Reference to a resource available in a different APIs
    PurchasedReservation:
      title: PurchasedReservation
      required:
      - datedServiceJourneyRef
      - reservationId
      type: object
      properties:
        reservationId:
          type: string
          description: ID and version of the Reservation.
          format: uuid
          examples:
          - de3299ae-b54c-4747-b915-d8536e1a9741
        datedServiceJourneyRef:
          $ref: '#/components/schemas/RefType'