Entur Purchase Windows API

openapi: 3.2.0
info:
  title: Entur Purchase Windows API
  version: 2026.10.0
  description: 'Operations tagged purchase-windows across 2 of this provider''s published API definitions: entur-products-openapi.json, entur-products-openapi.yml. Each path carries the servers of the definition it was published in.'
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: purchase-windows
paths:
  /purchase-windows:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - purchase-windows
      summary: Retrieves purchase window by fareFrame id or organisation id
      operationId: purchase-windows_getAll
      parameters:
      - name: orgId
        in: query
        description: The unique organisation id to identify the owner of the data
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: fareFrameId
        in: query
        description: The unique fareFrame id to identify the owner of the data
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: languageCode
        in: query
        description: The language code from ISO-639-3
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: If-None-Match
        in: header
        description: Used to make conditional requests. It allows the client to provide an ETag value, and the server will process the request only if the ETag does not match the current version of the resource.
        required: false
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Returns the info
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseWindow'
        '304':
          description: Not Modified
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                type: string
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                type: string
      security:
      - basic_auth: []
      x-entur-permissions:
        value: product-api-access:les
    post:
      tags:
      - purchase-windows
      summary: Create a purchase window
      operationId: purchase-windows_create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseWindowInsert'
        required: true
      responses:
        '204':
          description: Entity created successfully
        '400':
          description: Validation errors
          content:
            application/problem+json:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                type: string
        '409':
          description: Already registered
          content:
            application/problem+json:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                type: string
      security:
      - basic_auth: []
      x-entur-permissions:
        value: product-api-access:endre
    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
  /purchase-windows/{id}:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - purchase-windows
      summary: Retrives a purchase window by id
      operationId: purchase-windows_getById
      parameters:
      - name: id
        in: path
        description: The unique id to identify a purchase window
        required: true
        style: simple
        explode: false
        schema:
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
      - name: version
        in: query
        description: The id for the version of the purchase window
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: languageCode
        in: query
        description: The language code from ISO-639-3
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: If-None-Match
        in: header
        description: Used to make conditional requests. It allows the client to provide an ETag value, and the server will process the request only if the ETag does not match the current version of the resource.
        required: false
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Returns the info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseWindow'
        '304':
          description: Not Modified
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                type: string
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                type: string
      security:
      - basic_auth: []
      x-entur-permissions:
        value: product-api-access:les
    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
  /purchase-windows/{id}/{version}:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - purchase-windows
      summary: Retrives a purchase window by id and version
      operationId: purchase-windows_getByIdAndVersion
      parameters:
      - name: id
        in: path
        description: The unique id to identify a purchase window
        required: true
        style: simple
        explode: false
        schema:
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
      - name: version
        in: path
        description: The id for the version of the purchase window
        required: true
        style: simple
        explode: false
        schema:
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
      - name: Accept-Language
        in: header
        description: The language code from ISO-639-3
        required: false
        style: simple
        explode: false
        schema:
          type: string
      - name: If-None-Match
        in: header
        description: Used to make conditional requests. It allows the client to provide an ETag value, and the server will process the request only if the ETag does not match the current version of the resource.
        required: false
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Returns the info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseWindow'
        '304':
          description: Not Modified
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                type: string
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                type: string
      security:
      - basic_auth: []
      x-entur-permissions:
        value: product-api-access:les
    put:
      tags:
      - purchase-windows
      summary: Update a purchase window
      operationId: purchase-windows_update
      parameters:
      - name: id
        in: path
        description: The unique id to identify a purchase window
        required: true
        style: simple
        explode: false
        schema:
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
      - name: version
        in: path
        description: The id for the version of the purchase window
        required: true
        style: simple
        explode: false
        schema:
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseWindowInsert'
        required: true
      responses:
        '204':
          description: Entity updated successfully
        '400':
          description: Validation errors
          content:
            application/problem+json:
              schema:
                type: string
        '401':
          description: Missing Authorization
          content:
            application/problem+json:
              schema:
                type: string
        '403':
          description: Authorization failed
          content:
            application/problem+json:
              schema:
                type: string
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                type: string
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                type: string
      security:
      - basic_auth: []
      x-entur-permissions:
        value: product-api-access:endre
    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
  /v1/purchase-windows/{id}:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - purchase-windows
      summary: Retrieves a purchase window by id
      operationId: purchase-windows_getByIdV2
      parameters:
      - name: id
        in: path
        description: The unique id to identify a purchase window
        required: true
        style: simple
        explode: false
        schema:
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
      - name: Accept-Language
        in: header
        description: The language code from ISO-639-3
        required: false
        style: simple
        explode: false
        schema:
          type: string
      - name: startDate
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: endDate
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: status
        in: query
        description: The version status of the purchase window
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: fromDate
        in: query
        description: The from date of the purchase windows version
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: toDate
        in: query
        description: The to date of the purchase windows version
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: If-None-Match
        in: header
        description: Used to make conditional requests. It allows the client to provide an ETag value, and the server will process the request only if the ETag does not match the current version of the resource.
        required: false
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Returns the info
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseWindow'
        '304':
          description: Not Modified
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                type: string
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                type: string
      security:
      - basic_auth: []
      x-entur-permissions:
        value: product-api-access:les
    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
components:
  schemas:
    PurchaseWindowInsert:
      required:
      - fareFrameRef
      - id
      - name
      - version
      type: object
      properties:
        description:
          type: array
          description: Description represented in different languages. Language codes are ISO-639.
          items:
            $ref: '#/components/schemas/TextInLanguage'
        fareFrameRef:
          $ref: '#/components/schemas/VersionOfObjectRef'
        id:
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
          description: Id.
          examples:
          - NSB:PurchaseWindow:90days
        latestTime:
          type: string
          description: Latest time.
          examples:
          - '23:59:59'
        limitingRule:
          $ref: '#/components/schemas/LimitingRule'
        maxmumPeriodBeforeDeparture:
          type: string
          description: Maximum period before departure.
          examples:
          - PT2160H
        minimumPeriodBeforeDeparture:
          type: string
          description: Minimum period before departure.
          examples:
          - PT2160H
        name:
          type: array
          description: PurchaseWindow Name represented in different languages. Language codes are ISO-639.
          items:
            $ref: '#/components/schemas/TextInLanguage'
        purchaseWhen:
          type: string
          description: When to purchase.
          enum:
          - TIME_OF_TRAVEL_ONLY
          - DAY_OF_TRAVEL_ONLY
          - ADVANCE_ONLY
          - UNTIL_PREVIOUS_DAY
          - ADVANCE_AND_DAY_OF_TRAVEL
          - OTHER
          examples:
          - ADVANCE_AND_DAY_OF_TRAVEL
        version:
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
          description: PurchaseWindow version.
          examples:
          - NSB:Version:V1
    VersionOfObjectRef:
      required:
      - nameOfClass
      - ref
      - version
      type: object
      properties:
        nameOfClass:
          minLength: 1
          type: string
          description: Name of class.
        ref:
          minLength: 1
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
          description: The netex id reference to the object.
        version:
          type: string
          description: Version.
      description: Fare frame ref.
    PurchaseWindow:
      required:
      - changed
      - created
      - fareFrameRef
      - id
      - modification
      - nameOfClass
      - status
      - version
      type: object
      properties:
        changed:
          type: string
          description: Changed datetime.
          format: date-time
        compatibleWithVersionRef:
          type: string
          description: Compatible with version.
        created:
          type: string
          description: Created datetime.
          format: date-time
        derivedFromVersionRef:
          type: string
          description: Derived from version.
        description:
          type: array
          description: Description represented in different languages. Language codes are ISO-639.
          items:
            $ref: '#/components/schemas/TextInLanguage'
        fareFrameRef:
          $ref: '#/components/schemas/VersionOfObjectRef'
        id:
          minLength: 1
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
          description: Id.
          examples:
          - NSB:PurchaseWindow:Child
        latestTime:
          type: string
          description: Latest time to purchase.
          examples:
          - '23:59:59.999999999'
        limitingRule:
          $ref: '#/components/schemas/LimitingRule'
        maxmumPeriodBeforeDeparture:
          type: string
          description: Maximum period before departure.
          examples:
          - '23:59:59.999999999'
        minimumPeriodBeforeDeparture:
          type: string
          description: Minimum period before departure.
          examples:
          - '01:59:59.999999999'
        modification:
          type: string
          description: Modification status.
          enum:
          - NEW
          - REVISE
          - DELETE
          examples:
          - NEW
        name:
          type: array
          description: PurchaseWindow Name represented in different languages. Language codes are ISO-639.
          items:
            $ref: '#/components/schemas/TextInLanguage'
        nameOfClass:
          type: string
          description: Name of class.
          examples:
          - PurchaseWindow
        purchaseWhen:
          type: string
          description: When to purchase.
          enum:
          - TIME_OF_TRAVEL_ONLY
          - DAY_OF_TRAVEL_ONLY
          - ADVANCE_ONLY
          - UNTIL_PREVIOUS_DAY
          - ADVANCE_AND_DAY_OF_TRAVEL
          - OTHER
          examples:
          - ADVANCE_AND_DAY_OF_TRAVEL
        status:
          type: string
          description: Status
          enum:
          - DRAFT
          - PROPOSED
          - VERSIONED
          - DEPRECATED
          examples:
          - DRAFT
        version:
          minLength: 1
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
          description: PurchaseWindow version.
          examples:
          - NSB:Version:V1
      description: A PurchaseWindow
    LimitingRule:
      required:
      - changed
      - created
      - fareFrameRef
      - id
      - modification
      - nameOfClass
      - status
      type: object
      properties:
        canBeCumulative:
          type: boolean
          description: CanBeCumulative.
        changed:
          type: string
          description: Changed datetime.
          readOnly: true
        compatibleWithVersionRef:
          type: string
          description: Compatible with version.
        created:
          type: string
          description: Created datetime.
          readOnly: true
        derivedFromVersionRef:
          type: string
          description: Derived from version.
        description:
          type: array
          description: Description.
          items:
            $ref: '#/components/schemas/TextInLanguage'
        discountAsPercentage:
          type: number
          description: DiscountAsPercentage.
          format: float
        discountAsValue:
          type: number
          description: DiscountAsValue.
          format: float
        fareFrameRef:
          $ref: '#/components/schemas/VersionOfObjectRef'
        id:
          minLength: 1
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
          description: Id.
        maximumPrice:
          type: string
          description: MaximumPrice.
          examples:
          - '164.0'
        maximumPriceAsPercentage:
          type: number
          description: MaximumPriceAsPercentage.
          format: double
        minimumLimitPrice:
          type: string
          description: MinimumLimitPrice.
          examples:
          - '164.0'
        minimumPrice:
          type: string
          description: MinimumPrice.
          examples:
          - '164.0'
        modification:
          type: string
          description: Modification status.
          readOnly: true
          enum:
          - NEW
          - REVISE
          - DELETE
          examples:
          - NEW
        name:
          type: array
          description: Name.
          items:
            $ref: '#/components/schemas/TextInLanguage'
        nameOfClass:
          type: string
          description: Name of class.
          readOnly: true
          examples:
          - LimitingRule
        status:
          type: string
          description: Status.
          readOnly: true
          enum:
          - DRAFT
          - PROPOSED
          - VERSIONED
          - DEPRECATED
          examples:
          - DRAFT
        version:
          minLength: 1
          pattern: ^([A-Z]{3}):([A-Za-z]*):([0-9A-Za-z_\-]*)$
          type: string
          description: Version.
          examples:
          - NSB:Version:V1
      description: A LimitingRule
    TextInLanguage:
      required:
      - lang
      - value
      type: object
      properties:
        lang:
          minLength: 1
          type: string
          description: Language code.
          examples:
          - nob
        value:
          minLength: 1
          type: string
          description: The text.
      description: Text in a specific language.
  parameters:
    X-Correlation-Id:
      name: X-Correlation-Id
      in: header
      description: Correlation id
      required: false
      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
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- entur-products-openapi.json
- entur-products-openapi.yml