openapi: 3.2.0
info:
  title: Products V3 Supplement product API
  description: '**This API specification is a draft and is not yet implemented. Endpoints, schemas, and

    behavior are subject to change without notice.**


    This API provides services to read and maintain products and fare data for public transport in Norway.'
  contact:
    name: Team Produkt
    email: teamprodukt@entur.org
  version: 2026.10.1
  x-stability-level: draft
servers:
- url: https://api.entur.io/products
  description: Production environment
- url: https://api.staging.entur.io/products
  description: Staging environment
- url: https://api.dev.entur.io/products
  description: Development environment
security:
- jwt: []
tags:
- name: Supplement product
  description: 'A supplement product can be purchased in addition to a preassigned fare product. Examples of supplement product types include:

    - Seat reservation

    - Bicycle

    - Animal

    - Meal

    - Wi-fi

    - Luggage

    - Parking'
paths:
  /v3/supplement-products:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    post:
      tags:
      - Supplement product
      summary: Create a new supplement product
      description: Create a new supplement product. A new version will be created with version number 1.
      operationId: createSupplementProduct
      requestBody:
        description: Supplement product to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementProductRequest'
            examples:
              bicycle:
                $ref: '#/components/examples/bicycle'
              seatReservation:
                $ref: '#/components/examples/seatReservation'
              dog:
                $ref: '#/components/examples/dog'
              luggage:
                $ref: '#/components/examples/luggage'
              parking:
                $ref: '#/components/examples/parking'
              upgrade:
                $ref: '#/components/examples/upgrade'
        required: true
      responses:
        '201':
          description: Supplement product created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementProductResponse'
              examples:
                parking:
                  $ref: '#/components/examples/parking-2'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          description: Conflict - Supplement product already exists
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                conflict:
                  summary: Supplement product already exists
                  value:
                    type: https://developer.entur.org/errors/conflict
                    title: Conflict
                    status: 409
                    detail: Supplement product with privateCode '123' already exists.
      x-entur-permissions:
        value: product-api-access:endre
  /v3/supplement-products/{id}:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Supplement product
      summary: Get the active version of a supplement product
      description: Retrieve the version of the supplement product that is active on the given date.
      operationId: getSupplementProduct
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/validOnDate'
      responses:
        '200':
          description: The supplement product version active on the given date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementProductResponse'
              examples:
                parking:
                  $ref: '#/components/examples/parking-2'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Supplement product not found, or no version is active on the given travel date
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                notFound:
                  summary: Supplement product not found
                  value:
                    type: https://developer.entur.org/errors/not-found
                    title: Not Found
                    status: 404
                    detail: SupplementProduct 'EXA:SupplementProduct:456' not found.
                noActiveVersion:
                  summary: No version active on the travel date
                  value:
                    type: https://developer.entur.org/errors/not-found
                    title: Not Found
                    status: 404
                    detail: No version of SupplementProduct 'EXA:SupplementProduct:456' is active on 2026-12-01.
      x-entur-permissions:
        value: product-api-access:les
    post:
      tags:
      - Supplement product
      summary: Create a new version of a supplement product
      description: Create a new version of existing supplement product. The added version will be in DRAFT status, and will be created with version number n+1. The version will not be active until a start date is set and the version is published.
      operationId: createSupplementProductVersion
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        description: The updated version of supplement product. The existing data in supplement product will be replaced by this one.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementProductRequest'
            examples:
              bicycle:
                $ref: '#/components/examples/bicycle'
              seatReservation:
                $ref: '#/components/examples/seatReservation'
              dog:
                $ref: '#/components/examples/dog'
              luggage:
                $ref: '#/components/examples/luggage'
              parking:
                $ref: '#/components/examples/parking'
              upgrade:
                $ref: '#/components/examples/upgrade'
        required: true
      responses:
        '201':
          description: Supplement product created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementProductResponse'
              examples:
                parking:
                  $ref: '#/components/examples/parking-2'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          description: Conflict - Supplement product already exists
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                conflict:
                  summary: Supplement product already exists
                  value:
                    type: https://developer.entur.org/errors/conflict
                    title: Conflict
                    status: 409
                    detail: Supplement product with privateCode '123' already exists.
      x-entur-permissions:
        value: product-api-access:endre
  /v3/supplement-products/{id}/versions:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Supplement product
      summary: List versions of a supplement product
      description: 'Retrieve all versions of a supplement product by its NeTEx ID, including drafts and

        proposals.'
      operationId: getSupplementProductVersions
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: List of supplement product versions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VersionResponse'
              examples:
                versionHistory:
                  $ref: '#/components/examples/versionHistory'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Supplement product not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                notFound:
                  summary: Supplement product not found
                  value:
                    type: https://developer.entur.org/errors/not-found
                    title: Not Found
                    status: 404
                    detail: SupplementProduct 'EXA:SupplementProduct:456' not found.
      x-entur-permissions:
        value: product-api-access:les
  /v3/supplement-products/{id}/{version}:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Supplement product
      summary: Get a supplement product version
      description: 'Retrieve the complete supplement product for a specific version,

        identified by NeTEx version ID or version number.'
      operationId: getSupplementProductVersion
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/version'
      responses:
        '200':
          description: Supplement product version found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementProductResponse'
              examples:
                parking:
                  $ref: '#/components/examples/parking-2'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Supplement product or version not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                notFound:
                  summary: Supplement product version not found
                  value:
                    type: https://developer.entur.org/errors/not-found
                    title: Not Found
                    status: 404
                    detail: Version 'EXA:Version:SP-abc123-v1' not found for SupplementProduct 'EXA:SupplementProduct:456'.
      x-entur-permissions:
        value: product-api-access:les
    put:
      tags:
      - Supplement product
      summary: Update a version of a supplement product
      description: Update the version of a supplement product. The version will not be active until a start date is set and the version is published.
      operationId: updateSupplementProductVersion
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/version'
      requestBody:
        description: The updated version of supplement product. The existing data in supplement product will be replaced by this one.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementProductRequest'
            examples:
              bicycle:
                $ref: '#/components/examples/bicycle'
              seatReservation:
                $ref: '#/components/examples/seatReservation'
              dog:
                $ref: '#/components/examples/dog'
              luggage:
                $ref: '#/components/examples/luggage'
              parking:
                $ref: '#/components/examples/parking'
              upgrade:
                $ref: '#/components/examples/upgrade'
        required: true
      responses:
        '200':
          description: Supplement product updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementProductResponse'
              examples:
                parking:
                  $ref: '#/components/examples/parking-2'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          description: Supplement product not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                conflict:
                  summary: Supplement product not found
                  value:
                    type: https://developer.entur.org/errors/conflict
                    title: Not Found
                    status: 404
                    detail: Supplement product not found.
      x-entur-permissions:
        value: product-api-access:endre
components:
  examples:
    dog:
      summary: Dog onboard
      value:
        ownerOrganisationId: 1
        names:
        - lang: en-GB
          value: Dog
        - lang: nb-NO
          value: Hund
        descriptions:
        - lang: en-GB
          value: Bring your dog onboard the train.
        - lang: nb-NO
          value: Ta med hunden din ombord på toget.
        status: DRAFT
        startDate: '2025-01-01'
        supplementProductType: DOG
        chargingMomentType: BEFORE_TRAVEL
        conditionsSummary:
          exchangeable: true
          refundable: true
          fareStructureType: POINT_TO_POINT_FARE
        vatGroup: TRANSPORT_AND_TICKETS_VAT
        purchaseWindowRef: EXA:PurchaseWindow:90days
        usageValidityPeriodRef: EXA:UsageValidityPeriod:60minutes
        entitlementRequiredRefs:
        - EXA:EntitlementRequired:StandardTicket
        validityParameters:
        - groupingType: OR
          validityParameterType: ZONE
          validityParameterRefs:
          - EXA:FareZone:A
          - EXA:FareZone:B
    seatReservation:
      summary: Seat reservation
      value:
        ownerOrganisationId: 1
        names:
        - lang: en-GB
          value: Seat reservation
        - lang: nb-NO
          value: Setereservasjon
        descriptions:
        - lang: en-GB
          value: Mandatory seat reservation for all passengers on Bergensbanen.
        - lang: nb-NO
          value: Obligatorisk setereservasjon for alle passasjerer på Bergensbanen.
        status: DRAFT
        startDate: '2025-01-01'
        endDate: '2025-12-31'
        supplementProductType: SEAT_RESERVATION
        chargingMomentType: BEFORE_TRAVEL
        conditionsSummary:
          exchangeable: true
          refundable: false
          fareStructureType: NETWORK_FLAT_FARE
        vatGroup: TRANSPORT_AND_TICKETS_VAT
        purchaseWindowRef: EXA:PurchaseWindow:120days
        usageValidityPeriodRef: EXA:UsageValidityPeriod:DuringTravel
        entitlementRequiredRefs:
        - EXA:EntitlementRequired:StandardTicket
        - EXA:EntitlementRequired:FlexibleTicket
        validityParameters:
        - groupingType: OR
          validityParameterType: LINE
          validityParameterRefs:
          - EXA:Line:X1
    luggage:
      summary: Extra luggage
      value:
        ownerOrganisationId: 1
        names:
        - lang: en-GB
          value: Extra luggage
        - lang: nb-NO
          value: Ekstra bagasje
        descriptions:
        - lang: en-GB
          value: Bring additional luggage beyond the standard allowance.
        - lang: nb-NO
          value: Ta med ekstra bagasje utover standard bagasjemengde.
        status: DRAFT
        startDate: '2025-01-01'
        endDate: '2025-12-31'
        supplementProductType: EXTRA_LUGGAGE
        chargingMomentType: BEFORE_TRAVEL
        conditionsSummary:
          exchangeable: true
          refundable: true
          fareStructureType: POINT_TO_POINT_FARE
        vatGroup: TRANSPORT_AND_TICKETS_VAT
        purchaseWindowRef: EXA:PurchaseWindow:120days
        usageValidityPeriodRef: EXA:UsageValidityPeriod:DuringTravel
        entitlementRequiredRefs:
        - EXA:EntitlementRequired:StandardTicket
        - EXA:EntitlementRequired:FlexibleTicket
        validityParameters:
        - groupingType: OR
          validityParameterType: LINE
          validityParameterRefs:
          - EXA:Line:X1
    parking:
      summary: Parking reservation
      value:
        privateCodes:
        - '123'
        ownerOrganisationId: 47
        names:
        - lang: en-GB
          value: Parking reservation
        - lang: nb-NO
          value: Parkeringsreservasjon
        descriptions:
        - lang: en-GB
          value: Reserve a parking spot at the station.
        - lang: nb-NO
          value: Reserver parkeringsplass på stasjonen.
        status: DRAFT
        startDate: '2025-01-01'
        supplementProductType: PARKING
        chargingMomentType: BEFORE_TRAVEL
        conditionsSummary:
          exchangeable: false
          refundable: false
          fareStructureType: NETWORK_FLAT_FARE
        vatGroup: TRANSPORT_AND_TICKETS_VAT
        purchaseWindowRef: EXA:PurchaseWindow:120days
        usageValidityPeriodRef: EXA:UsageValidityPeriod:30days
        entitlementRequiredRefs:
        - EXA:EntitlementRequired:PeriodTicket30days
        validityParameters:
        - groupingType: OR
          validityParameterType: PARKING
          validityParameterRefs:
          - NSR:Parking:P01
          - NSR:Parking:P02
          - NSR:Parking:P03
    upgrade:
      summary: First class upgrade with entitlement requirement
      value:
        ownerOrganisationId: 1
        names:
        - lang: en-GB
          value: First Class Upgrade
        - lang: nb-NO
          value: Oppgradering til 1. klasse
        descriptions:
        - lang: en-GB
          value: Valid on the given departure and require a valid ticket.
        - lang: nb-NO
          value: Gyldig på en gitt avgang og krever gyldig billett.
        status: DRAFT
        startDate: '2025-01-01'
        supplementProductType: UPGRADE
        chargingMomentType: BEFORE_TRAVEL
        conditionsSummary:
          exchangeable: false
          refundable: false
          fareStructureType: NETWORK_FLAT_FARE
        vatGroup: TRANSPORT_AND_TICKETS_VAT
        purchaseWindowRef: EXA:PurchaseWindow:120days
        usageValidityPeriodRef: EXA:UsageValidityPeriod:DuringTravel
        entitlementRequiredRefs:
        - EXA:EntitlementRequired:StandardTicket
        - EXA:EntitlementRequired:FlexibleTicket
        validityParameters:
        - groupingType: OR
          validityParameterType: LINE
          validityParameterRefs:
          - EXA:Line:X1
    bicycle:
      summary: Bicycle reservation
      value:
        ownerOrganisationId: 1
        names:
        - lang: en-GB
          value: Bike reservation
        - lang: nb-NO
          value: Sykkelreservasjon
        descriptions:
        - lang: en-GB
          value: Valid on the given departure and require a valid ticket for traveller who brings the bike.
        - lang: nb-NO
          value: Gyldig på en gitt avgang og krever gyldig billett for den reisende som reiser med sykkel.
        status: DRAFT
        startDate: '2025-01-01'
        supplementProductType: BICYCLE
        chargingMomentType: BEFORE_TRAVEL
        conditionsSummary:
          exchangeable: true
          refundable: true
          fareStructureType: NETWORK_FLAT_FARE
        vatGroup: TRANSPORT_AND_TICKETS_VAT
        purchaseWindowRef: EXA:PurchaseWindow:120days
        usageValidityPeriodRef: EXA:UsageValidityPeriod:DuringTravel
        entitlementRequiredRefs:
        - EXA:EntitlementRequired:SingleTicket
        - EXA:EntitlementRequired:PeriodTicket
        validityParameters:
        - groupingType: OR
          validityParameterType: LINE
          validityParameterRefs:
          - EXA:Line:X1
    parking-2:
      summary: Parking reservation response
      value:
        privateCodes:
        - '123'
        id: EXA:SupplementProduct:456
        versionId: EXA:Version:07ce871e-b84d-47c0-99ba-c7fdb5fa4df9
        versionNumber: 1
        ownerOrganisationId: 47
        datasource:
          id: some-client-system
        status: VERSIONED
        startDate: '2025-01-01'
        names:
        - lang: en-GB
          value: Parking reservation
        - lang: nb-NO
          value: Parkeringsreservasjon
        descriptions:
        - lang: en-GB
          value: Reserve a parking spot at the station.
        - lang: nb-NO
          value: Reserver parkeringsplass på stasjonen.
        supplementProductType: PARKING
        chargingMomentType: BEFORE_TRAVEL
        conditionsSummary:
          exchangeable: false
          refundable: false
          fareStructureType: NETWORK_FLAT_FARE
        vatGroup: TRANSPORT_AND_TICKETS_VAT
        purchaseWindowRef: EXA:PurchaseWindow:120days
        usageValidityPeriodRef: EXA:UsageValidityPeriod:30days
        entitlementRequiredRefs:
        - EXA:EntitlementRequired:PeriodTicket30days
        validityParameters:
        - groupingType: OR
          validityParameterType: PARKING
          validityParameterRefs:
          - NSR:Parking:P01
          - NSR:Parking:P02
          - NSR:Parking:P03
        fareTableRefs:
        - EXA:FareTable:parking-2025
    versionHistory:
      summary: Example version history
      value:
      - id: EXA:Version:853a7d14-794e-4af5-b569-301711a26e26
        status: VERSIONED
        startDate: '2025-01-01'
        endDate: '2025-12-31'
        created: '2024-12-01T10:00:00Z'
        changed: '2024-12-01T10:00:00Z'
        published: '2024-12-30T10:00:00Z'
        number: 1
      - id: EXA:Version:e7104d26-16a5-4db5-aa42-b32ae0a3f684
        status: VERSIONED
        startDate: '2026-01-01'
        created: '2025-12-01T10:00:00Z'
        changed: '2025-12-01T10:00:00Z'
        published: '2025-12-01T13:00:00Z'
        number: 2
      - id: EXA:Version:6be856a5-dd98-496b-b3f2-ad9939270ec3
        status: PROPOSED
        startDate: '2026-07-01'
        created: '2026-06-01T10:00:00Z'
        changed: '2026-06-01T10:00:00Z'
  parameters:
    version:
      name: version
      in: path
      description: The netex ID or sequence number of the version to retrieve
      required: true
      style: simple
      explode: false
      schema:
        pattern: ^(([A-Z]{3}):Version:([0-9A-Za-z_\-]*)|[1-9][0-9]*)$
        type: string
      examples:
        default:
          value: ENT:Version:001
    X-Correlation-Id:
      name: X-Correlation-Id
      in: header
      description: Correlation id
      required: false
      style: simple
      explode: false
      schema:
        type: string
    validOnDate:
      name: validOnDate
      in: query
      description: 'The date that the element should be valid for, e.g. the travel date.

        Defaults to the current date.

        '
      required: false
      style: form
      explode: true
      schema:
        type: string
        format: date
      examples:
        default:
          value: '2026-12-01'
    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
    id:
      name: id
      in: path
      description: The netex ID of the element to retrieve
      required: true
      style: simple
      explode: false
      schema:
        pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
        type: string
      examples:
        default:
          value: ENT:PreassignedFareProduct:001
  responses:
    BadRequestError:
      description: Bad request - Invalid data or schema violation
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            schemaViolation:
              summary: Request does not match schema
              value:
                type: https://developer.entur.org/errors/bad-request
                title: Bad Request
                status: 400
                detail: Field 'name' is required.
            purchaseWindowNotFound:
              summary: Referenced purchase window not found
              value:
                type: https://developer.entur.org/errors/bad-request
                title: Bad Request
                status: 400
                detail: PurchaseWindow with id 'ENT:PurchaseWindow:120days' not found.
    ForbiddenError:
      description: Forbidden - Insufficient permissions
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            forbidden:
              summary: Access forbidden
              value:
                type: https://example.com/probs/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
    UnauthorizedError:
      description: Unauthorized - Authentication required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            unauthorized:
              summary: Authentication required
              value:
                type: https://example.com/probs/unauthorized
                title: Unauthorized
                status: 401
                detail: Authentication credentials were missing or invalid.
  schemas:
    SupplementProductType:
      type: string
      description: The type of the supplement product. This can be used to determine which parameters are relevant for the product.
      enum:
      - SEAT_RESERVATION
      - BICYCLE
      - DOG
      - ANIMAL
      - MEAL
      - WIFI
      - EXTRA_LUGGAGE
      - PENALTY
      - UPGRADE
      - JOURNEY_EXTENSION
      - JOURNEY_ADD_ON
      - EVENT_ADD_ON
      - PARKING
    VatGrpupType:
      type: string
      description: VAT group type. This is used to determine which VAT rate applies to a product. The VAT group type is determined by the product type and the country of sale. For example, in Norway, food products are subject to a reduced VAT rate of 15%, while other products are subject to the standard VAT rate of 25%. In this case, food products would be classified as FOOD_VAT, while other products would be classified as GENERAL_VAT.
      default: TRANSPORT_AND_TICKETS_VAT
      enum:
      - EXCEPTION_FROM_VAT
      - GENERAL_VAT
      - FOOD_VAT
      - TRANSPORT_AND_TICKETS_VAT
    ProblemDetails:
      required:
      - detail
      - status
      - title
      - type
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type.
          format: uri
          examples:
          - https://developer.entur.org/errors/bad-request
        title:
          type: string
          description: Short, human-readable summary of the problem type.
          examples:
          - Bad Request
        status:
          type: integer
          description: The HTTP status code.
          format: int32
          examples:
          - 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          examples:
          - The supplied ruleId is not a valid UUID.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence.
          format: uri
          examples:
          - https://api.example.com/requests/12345
      description: RFC 9457 Problem Details
    LocalizedString:
      type: array
      items:
        required:
        - lang
        - value
        type: object
        properties:
          lang:
            pattern: ^[a-z]{2}-[A-Z]{2}$
            type: string
            description: BCP-47 language tag (e.g., 'nb-NO', 'en-GB').
            examples:
            - nb-NO
          value:
            type: string
            description: The localized string value for the specified lang.
    FareTableRef:
      required:
      - ref
      - version
      type: object
      properties:
        ref:
          pattern: ^([A-Z]{3}):FareTable:([0-9A-Za-z_\-]*)$
          type: string
          description: NeTEx id of the FareTable that prices this supplement product.
          examples:
          - ENT:FareTable:bike-supplement
        version:
          type: string
          description: NeTEx version id of the referenced FareTable.
          examples:
          - ENT:Version:8f1b2c3d
      description: 'A reference to a versioned FareTable that prices a supplement product. The priceable object

        side authors this link (mirroring products-spring), so the fare table version is required to

        pin the exact fare table the link resolves to.

        '
    ConditionsSummary:
      required:
      - exchangeable
      - fareStructureType
      - refundable
      type: object
      properties:
        exchangeable:
          type: boolean
          description: Whether the supplement product is exchangeable.
          examples:
          - true
        refundable:
          type: boolean
          description: Whether the supplement product is refundable.
          examples:
          - false
        fareStructureType:
          $ref: '#/components/schemas/FareStructureType'
    VersionResponse:
      required:
      - changed
      - created
      - id
      - startDate
      - status
      type: object
      properties:
        id:
          pattern: ^([A-Z]{3}):Version:([0-9A-Za-z_\-]*)$
          type: string
          description: The netex id reference to the object.
          examples:
          - EXA:Version:001
        number:
          type: integer
          description: Version number of the version. Only present when versionStatus is VERSIONED. Starts at 1 for a new product and is incremented by 1 for each new version.
          format: int64
          examples:
          - 1
        status:
          $ref: '#/components/schemas/VersionStatus'
        startDate:
          type: string
          description: The start date of the version.
          format: date
        endDate:
          type: string
          description: The end date of the version.
          format: date
        published:
          type: string
          description: Timestamp for when the version was published (set to status VERSIONED).
          format: date-time
        created:
          type: string
          description: Created datetime
          format: date-time
        changed:
          type: string
          description: Changed datetime
          format: date-time
    GenericParameterAssignmentGroupingType:
      type: string
      description: How multiple GPA parameters should be combined (AND/OR)
      enum:
      - AND
      - OR
    SupplementProductRequest:
      required:
      - chargingMomentType
      - conditionsSummary
      - entitlementRequiredRefs
      - names
      - purchaseWindowRef
      - startDate
      - status
      - supplementProductType
      - usageValidityPeriodRef
      - validityParameters
      - vatGroup
      type: object
      properties:
        privateCodes:
          type: array
          description: Optional external system identifiers.
          items:
            type: string
            examples:
            - '123'
          default: []
        ownerOrganisationId:
          minimum: 1
          type: integer
          description: Internal id of the organisation that owns this element. Omit it to use the organisation in the access token, which is what a caller acting for itself should do. Supplying a different organisation requires permission to act on behalf of that organisation.
          format: int64
        names:
          $ref: '#/components/schemas/LocalizedString'
        descriptions:
          $ref: '#/components/schemas/LocalizedString'
        startDate:
          type: string
          description: The start date of the version.
          format: date
        endDate:
          type: string
          description: The end date of the version (optional).
          format: date
        status:
          allOf:
          - $ref: '#/components/schemas/VersionStatus'
          - description: 'Status of the supplement product. Defaults to VERSIONED.


              - **DRAFT** - Under construction and not ready for operational use.

              - **PROPOSED** - Complete but pending review and approval.

              - **VERSIONED** - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.

              - **DEPRECATED** - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

              '
            examples:
            - VERSIONED
        chargingMomentType:
          $ref: '#/components/schemas/ChargingMomentType'
        supplementProductType:
          $ref: '#/components/schemas/SupplementProductType'
        conditionsSummary:
          $ref: '#/components/schemas/ConditionsSummary'
        vatGroup:
          $ref: '#/components/schemas/VatGrpupType'
        purchaseWindowRef:
          pattern: ^([A-Z]{3}):PurchaseWindow:([0-9A-Za-z_\-]*)$
          type: string
          description: 'NeTEx ID of a PurchaseWindow instance (Product Parameters API, /v3/parameters/purchase-windows). Available values are listed in the Product Parameters API.

            '
          examples:
          - ENT:PurchaseWindow:120days
        usageValidityPeriodRef:
          pattern: ^([A-Z]{3}):UsageValidityPeriod:([0-9A-Za-z_\-]*)$
          type: string
          description: 'NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period).

            Available values are listed in the Product Parameters API.


            **Not yet implemented:** this endpoint currently accepts but does not persist or return this field.

            '
          x-implementation-status: not-persisted
          examples:
          - ENT:UsageValidityPeriod:DuringTravel
        entitlementRequiredRefs:
          minItems: 1
          type: array
          description: 'List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required).

            Available values are listed in the Product Parameters API.


            **Not yet implemented:** this endpoint currently accepts but does not persist or return this field.

            '
          items:
            pattern: ^([A-Z]{3}):EntitlementRequired:([0-9A-Za-z_\-]*)$
            type: string
            description: NeTEx ID of an EntitlementRequired instance.
            examples:
            - ENT:EntitlementRequired:SingleTicket
          x-implementation-status: not-persisted
        validityParameters:
          type: array
          description: 'List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.


            **Not yet implemented:** this endpoint currently accepts but does not persist or return this field.

            '
          items:
            $ref: '#/components/schemas/ValidityParameters'
          x-implementation-status: not-persisted
        fareTableRefs:
          type: array
          description: 'References to the versioned FareTable instances that price this supplement product.


            The priceable object owns this link (as in products-spring): supply the fare tables that

            price it here on write. Prices themselves live on the fare table — create/update them via the

            pricing/fare-table API, then reference the fare table here. On read, `SupplementProductResponse`

            surfaces the resolved fare-table NeTEx ids.

            '
          items:
            $ref: '#/components/schemas/FareTableRef'
          default: []
    ChargingMomentType:
      type: string
      description: 'Charging moment type.


        Note: Currently, only `BEFORE_TRAVEL` is supported in Entur sales platform.

        '
      enum:
      - BEFORE_TRAVEL
      - ON_START_OF_TRAVEL
      - BEFORE_END_OF_TRAVEL
      - BEFORE_TRAVEL_THEN_ADJUST_AT_END_OF_TRAVEL
      - ON_START_THEN_ADJUST_AT_END_OF_TRAVEL
      - ON_START_THEN_ADJUST_AT_END_OF_FARE_DAY
      - ON_START_THEN_ADJUST_AT_END_OF_CHARGE_PERIOD
      - AT_END_OF_TRAVEL
      - AT_END_OF_FARE_DAY
      - AT_END_OF_CHARGE_PERIOD
      - FREE
      - ANY_TIME
      - OTHER
    SupplementProductResponse:
      required:
      - chargingMomentType
      - conditionsSummary
      - entitlementRequiredRefs
      - id
      - names
      - ownerOrganisationId
      - privateCodes
      - purchaseWindowRef
      - startDate
      - status
      - supplementProductType
      - usageValidityPeriodRef
      - validityParameters
      - vatGroup
      - versionId
      type: object
      properties:
        id:
          pattern: ^([A-Z]{3}):SupplementProduct:([0-9A-Za-z_\-]*)$
          type: string
          description: The NeTEx ID of the supplement product.
          examples:
          - BNR:SupplementProduct:123
        versionId:
          pattern: ^([A-Z]{3}):Version:([0-9A-Za-z_\-]*)$
          type: string
          description: The netex id reference to the object.
          examples:
          - EXA:Version:001
        versionNumber:
          type: integer
          description: Version number of the version. Only present when versionStatus is VERSIONED. Starts at 1 for a new product and is incremented by 1 for each new version.
          format: int64
          examples:
          - 1
        datasource:
          type: object
          properties:
            id:
              type: string
              description: The ID of the datasource.
              examples:
              - entur
          description: The datasource that owns this supplement product.
        privateCodes:
          type: array
          description: Optional external system identifiers.
          items:
            type: string
            examples:
            - '123'
          default: []
        ownerOrganisationId:
          type: integer
          description: Internal id of the organisation that owns this supplement product.
          format: int64
        names:
          $ref: '#/components/schemas/LocalizedString'
        descriptions:
          $ref: '#/components/schemas/LocalizedString'
        startDate:
          type: string
          description: The start date of the version.
          format: date
        endDate:
          type: string
          description: The end date of the version (optional).
          format: date
        status:
          allOf:
          - $ref: '#/components/schemas/VersionStatus'
          - description: 'Status of the supplement product.


              - **DRAFT** - Under construction and not ready for operational use.

              - **PROPOSED** - Complete but pending review and approval.

              - **VERSIONED** - Finalized and frozen; a new version must be created for further modifications. Remains authoritative for its validity period even after expiry.

              - **DEPRECATED** - Explicitly withdrawn and should not be used; indicates an active decision to retract, not a natural expiry.

              '
            examples:
            - VERSIONED
        chargingMomentType:
          $ref: '#/components/schemas/ChargingMomentType'
        supplementProductType:
          $ref: '#/components/schemas/SupplementProductType'
        conditionsSummary:
          $ref: '#/components/schemas/ConditionsSummary'
        vatGroup:
          $ref: '#/components/schemas/VatGrpupType'
        purchaseWindowRef:
          pattern: ^([A-Z]{3}):PurchaseWindow:([0-9A-Za-z_\-]*)$
          type: string
          description: 'NeTEx ID of a PurchaseWindow instance (Product Parameters API, /v3/parameters/purchase-windows). Available values are listed in the Product Parameters API.

            '
          examples:
          - ENT:PurchaseWindow:120days
        usageValidityPeriodRef:
          pattern: ^([A-Z]{3}):UsageValidityPeriod:([0-9A-Za-z_\-]*)$
          type: string
          description: 'NeTEx ID of a UsageValidityPeriod instance (limitations/usage-validity-period).

            Available values are listed in the Product Parameters API.


            **Not yet implemented:** this endpoint currently accepts but does not persist or return this field.

            '
          x-implementation-status: not-persisted
          examples:
          - ENT:UsageValidityPeriod:DuringTravel
        entitlementRequiredRefs:
          minItems: 1
          type: array
          description: 'List of NeTEx IDs of EntitlementRequired instances (limitations/entitlement-required).

            Available values are listed in the Product Parameters API.


            **Not yet implemented:** this endpoint currently accepts but does not persist or return this field.

            '
          items:
            pattern: ^([A-Z]{3}):EntitlementRequired:([0-9A-Za-z_\-]*)$
            type: string
            description: NeTEx ID of an EntitlementRequired instance.
            examples:
            - ENT:EntitlementRequired:SingleTicket
          x-implementation-status: not-persisted
        validityParameters:
          type: array
          description: 'List of validity parameters. The specified parameter tells where the supplement product is valid. This can be lines, zones, stops etc.


            **Not yet implemented:** this endpoint currently accepts but does not persist or return this field.

            '
          items:
            $ref: '#/components/schemas/ValidityParameters'
          x-implementation-status: not-persisted
        fareTableRefs:
          type: array
          description: 'NeTEx IDs of the FareTable instances that price this supplement product.


            Read-only. Prices themselves are not exposed here; use the pricing/fare-table API with these

            references to retrieve the actual prices. This lets clients discover the relevant fare

            tables for a priceable object directly, without fetching and scanning every fare table.

            '
          readOnly: true
          items:
            pattern: ^([A-Z]{3}):FareTable:([0-9A-Za-z_\-]*)$
            type: string
            description: NeTEx ID of a FareTable that prices this supplement product.
            examples:
            - ENT:FareTable:123
          default: []
    FareStructureType:
      type: string
      description: The type of fare structure. This indicates the method by which the fare is calculated, e.g. flat fare, zonal fare, point-to-point fare, etc.
      enum:
      - CAPPED_FLAT_FARE
      - CAPPED_POINT_TO_POINT_FARE
      - CAPPED_ZONAL_FARE
      - LINE_FLAT_FARE
      - NETWORK_FLAT_FARE
      - POINT_TO_POINT_FARE
      - POINT_TO_POINT_DISTANCE_FARE
      - STAGE_FARE
      - ZONE_FLAT_FARE
      - ZONE_SEQUENCE_FARE
      - ZONE_TO_ZONE_FARE
      - ZONE_COUNT_FARE
      - PENALTY_FARE
      - OTHER
    ValidityParameters:
      required:
      - groupingType
      - validityParameterRefs
      - validityParameterType
      type: object
      properties:
        groupingType:
          $ref: '#/components/schemas/GenericParameterAssignmentGroupingType'
        validityParameterType:
          type: string
          enum:
          - LINE
          - ZONE
          - ZONE_GROUP
          - STOP_PLACE
          - PARKING
          - ROUTE_SECTION
          - TARIFF_AUTHORITY
          - OPERATOR
          - TRANSPORT_MODE
          - FLEXIBLE_LINE
          - CLASS_OF_USE
          - FACILITY
          - SALES_CHANNEL
          - AUTHORITY
        validityParameterRefs:
          type: array
          description: List of references for the validity parameters
          items:
            pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
            type: string
            description: NeTEx reference to validity parameter
      examples:
      - groupingType: OR
        validityParameterType: LINE
        validityParameterRefs:
        - VYG:Line:L1
        - VYG:Line:L2
    VersionStatus:
      type: string
      enum:
      - DRAFT
      - PROPOSED
      - VERSIONED
      - DEPRECATED
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT