openapi: 3.2.0
info:
  title: Entur Contracts client API
  version: 2026.08.0
  contact:
    name: Entur Team Personalisering
    email: team.personalisering@entur.org
  termsOfService: http://entur.org
  description: 'Operations tagged Contracts client across 2 of this provider''s published API definitions: entur-personnel-tickets-openapi.json, entur-personnel-tickets-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.entur.io
security:
- jwt: []
tags:
- name: Contracts client
  description: API for handling loyalty program contracts.
paths:
  /customers/v2/benefits/contracts/claim-personnel-ticket:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    post:
      tags:
      - Contracts client
      summary: Claims a personnel ticket directly
      description: Claim a personnel ticket for the given customer profile. A personnel ticket may correspond to more than one contract in benefits, and this method will attempt to claim them all.
      operationId: claimPersonnelTicket
      parameters:
      - name: Authorization
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimPersonnelTicketRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimContractResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
    servers:
    - url: https://api.entur.io
  /customers/v2/benefits/contracts/validate-consumptions:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    post:
      tags:
      - Contracts client
      summary: Validate contract consumption
      description: Validate that the customer can consume given contracts
      operationId: validateContractUse
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateContractConsumptionRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ValidateContractConsumptionResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      x-entur-permissions:
        value:
          any:
          - benefits-contract-consumer:les
          - benefits-contract-consumer-global:les
    servers:
    - url: https://api.entur.io
  /customers/v2/benefits/contracts:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Contracts client
      summary: Return all contracts with possible filtering
      operationId: getAllContractsByParameters
      parameters:
      - name: uuid
        in: query
        description: Get the contract matching the uuid
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: uuid
      - name: customerNumber
        in: query
        description: Get all contracts where a customer is a contractConsumer using Unique Entur id
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: customerRef
        in: query
        description: Get all contracts where a customer is a contractConsumer using external customer id unique within an organisation
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: loyaltyProgramId
        in: query
        description: Get all contracts for a specific loyaltyProgram
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: contractHolder
        in: query
        description: Get all contracts for a specific contract holder. Use customerNumber as value
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: consumableAfter
        in: query
        description: Get all contracts which can be consumed after this date. Supports ISO 8601 date format
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: consumableBefore
        in: query
        description: Get all contracts which can be consumed before this date. Supports ISO 8601 date format
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: expirationDateAfter
        in: query
        description: Get all contracts with expiration date after this date. Supports ISO 8601 date format
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: expirationDateBefore
        in: query
        description: Get all contracts with expiration date before this date. Supports ISO 8601 date format
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: externalRef
        in: query
        description: Get all contracts by external reference. This is, for example, the personnel ticket code
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: organisationId
        in: query
        description: The organisation the contracts belong to. You must have an Internal token to use this.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
        examples:
          default:
            value: 3
      - name: sortBy
        in: query
        description: Properties to sort the response by. Multiple values can be specified
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - customerNumber
            - loyaltyProgramId
            - uuid
            - consumableFrom
            examples:
            - loyaltyProgramId
      - name: sortDirection
        in: query
        description: The sort direction if sortBy is specified
        required: false
        style: form
        explode: true
        schema:
          type: string
          enum:
          - asc
          - desc
          examples:
          - asc
      - name: page
        in: query
        description: The page to be retrieved. Starts at 1
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          default: 1
          examples:
          - 5
      - name: perPage
        in: query
        description: Number of items per page
        required: false
        style: form
        explode: true
        schema:
          maximum: 100
          minimum: 1
          type: integer
          default: 30
          examples:
          - 50
      - name: includeOrderLineEvents
        in: query
        description: 'Whether to include order line events in the response. Note: setting this to true may impact performance. Default false.'
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: includeConsumers
        in: query
        description: 'Whether to include contract consumers in the response. Supported formats are ''all'', ''none'' and ''contract-holder''. Note: setting this to ALL may impact performance. Default is ''contract-holder'''
        required: false
        style: form
        explode: true
        schema:
          pattern: all|none|contract-holder
          type: string
          enum:
          - all
          - none
          - contract-holder
          examples:
          - none
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PageOfContractResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      x-entur-permissions:
        value:
          any:
          - benefits-contract:les
          - benefits-contract-global:les
    servers:
    - url: https://api.entur.io
  /customers/v2/benefits/contracts/{externalRef}/by-external-ref:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Contracts client
      summary: Get contracts by external ref
      description: Finds contracts by external reference.
      operationId: getContractsByExternalRef
      parameters:
      - name: externalRef
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: organisationId
        in: query
        description: The organisation the contracts belong to, left empty will use orgID from token.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
        examples:
          default:
            value: 3
      - name: page
        in: query
        description: Selects a specific page in the collection
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          default: 1
          examples:
          - 1
      - name: perPage
        in: query
        description: Selects the number of elements per page
        required: false
        style: form
        explode: true
        schema:
          maximum: 100
          minimum: 1
          type: integer
          default: 30
          examples:
          - 5
      - name: includeOrderLineEvents
        in: query
        description: 'Whether to include order line events in the response. Note: setting this to true may impact performance. Default false.'
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: includeConsumers
        in: query
        description: 'Whether to include contract consumers in the response. Supported formats are ''all'', ''none'' and ''contract-holder''. Note: setting this to ALL may impact performance. Default is ''contract-holder'''
        required: false
        style: form
        explode: true
        schema:
          pattern: all|none|contract-holder
          type: string
          enum:
          - all
          - none
          - contract-holder
          examples:
          - none
      - name: Entur-Customer-Number
        in: header
        description: To identify logged in user and limit access per user
        required: false
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PageOfContractResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      x-entur-permissions:
        value:
          any:
          - benefits-contract:les
          - benefits-contract-jdir:les
          - benefits-contract-global:les
    servers:
    - url: https://api.entur.io
  /customers/v2/benefits/contract-consumers/{customerNumber}/contracts:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Contracts client
      description: Return all valid contracts by customer number. Returns only contracts with status VALID within timeframe.
      operationId: getAllValidContractsByCustomerNumber
      parameters:
      - name: customerNumber
        in: path
        required: true
        style: simple
        explode: false
        schema:
          exclusiveMinimum: 0
          type: integer
          format: int64
      - name: travelDate
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: organisationId
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: includeExpiredContracts
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: includeOrderLineEvents
        in: query
        description: 'Whether to include order line events in the response. Note: setting this to true may impact performance. Default false.'
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: includeConsumers
        in: query
        description: 'Whether to include contract consumers in the response. Supported formats are ''all'', ''none'' and ''contract-holder''. Note: setting this to ALL may impact performance. Default is ''contract-holder'''
        required: false
        style: form
        explode: true
        schema:
          pattern: all|none|contract-holder
          type: string
          enum:
          - all
          - none
          - contract-holder
          examples:
          - none
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContractResponse'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      x-entur-permissions:
        value:
          any:
          - benefits-contract-consumer:les
          - benefits-contract-consumer-jdir:les
          - benefits-contract-consumer-global:les
      summary: Get all valid contracts by customer number
      x-summary-source: derived
    servers:
    - url: https://api.entur.io
components:
  schemas:
    LoyaltyProgramFlatResponse:
      required:
      - descriptions
      - endDate
      - id
      - internalDescription
      - loyaltyProgramType
      - organisationId
      - productId
      - productVersion
      - startDate
      - status
      - versionNumber
      type: object
      properties:
        couponConfig:
          $ref: '#/components/schemas/CouponConfigResponse'
        defaultCouponsLimit:
          type: integer
          description: Deprecated. See couponConfig instead. How many coupons (eg. the maximum amount of usages) the underlying contracts of the loyalty program has.
          format: int64
          examples:
          - 10
        descriptions:
          type: array
          description: A list of human readable descriptions in different languages. Only one language per description is allowed.
          items:
            $ref: '#/components/schemas/LoyaltyProgramDescriptionResponse'
        endDate:
          type: string
          description: The end date of the loyaltyprogram. All contracts will expire when the loyaltyprogram expires. Supports ISO 8601 date format.
          format: date-time
        id:
          type: integer
          description: The id of the loyalty program
          format: int64
        internalDescription:
          type: string
          description: A human readable internal description of the loyalty program.
          examples:
          - Customer card with 15 % discount
        loyaltyProgramCode:
          type: string
          description: A word or code the customer can use to activate a loyalty program for themselves, set by the creator of the loyalty program
        loyaltyProgramType:
          type: string
          description: The type of loyalty program. Types include COUPONS, TIMED and POINTS. A time-based loyalty program specifies a duration a connected contract is valid. A point-based loyalty program has contracts keeping track of earning and burning of points. This also includes gift cards. A coupon-based loyalty programs specifies how many times a contract can be consumed. For compatibility reasons, UNMAPPED is also available for loyalty programs that has not yet been classified.
          enum:
          - TIMED
          - POINTS
          - COUPONS
          - UNMAPPED
          examples:
          - TIMED
        organisationId:
          type: integer
          description: The organisation that owns this loyalty program.
          format: int64
          examples:
          - 20
        productId:
          type: string
          description: The id of the product associated with this loyalty program.
        productVersion:
          type: string
          description: The version of the product associated with this loyalty program.
        startDate:
          type: string
          description: The start date of the loyaltyprogram. If specified ahead in time, the loyaltyprogram will get status = draft. Supports ISO 8601 date format.
          format: date-time
        status:
          type: string
          description: The current status of this loyalty program. Can be DRAFT, CURRENT, DEPRECATED
          enum:
          - DRAFT
          - CURRENT
          - DEPRECATED
        usageValidityPeriod:
          type: string
          description: 'The duration of a contract associated with this loyaltyprogram. This is set for loyalty program types TIMED and POINTS. The default value is null, which means the contract has an unlimited duration. This field uses the ISO 8601 duration format and accept the units: Days and Time. For example; ''P3DT12H30M5S'' represents a duration of three days, twelve hours, thirty minutes, and five seconds.'
          examples:
          - P3DT12H30M5S
        versionNumber:
          type: integer
          description: The version of this loyalty program.
          format: int64
      description: The current values for a loyalty program
    ContractResponse:
      required:
      - consumableFrom
      - createdAt
      - createdBy
      - lastChangedAt
      - lastChangedBy
      - loyaltyProgram
      - organisationId
      - status
      - uuid
      type: object
      properties:
        acceptanceDate:
          type: string
          description: When the contract was accepted by the customer
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        consumableFrom:
          type: string
          description: From when the contract can be consumed
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        contractConsumers:
          type: array
          description: The list of customers allowed to use the contract
          items:
            $ref: '#/components/schemas/ContractConsumerResponse'
        couponsLimit:
          type: integer
          description: How many coupons the contract has. Default is cascaded from Loyalty Program Version. If set, the contract will be blocked for usage when all coupons are used. Coupons are registered via an OrderLineEvent.
          format: int64
          examples:
          - 10
        createdAt:
          type: string
          description: When the contract was created
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        createdBy:
          type: string
          description: Which client created the contract
          examples:
          - 123e4567-e89b-12d3-a456-426655440000
        currentTotal:
          $ref: '#/components/schemas/TotalAmount'
        expirationDate:
          type: string
          description: When the contract expires
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        externalRef:
          type: string
          description: Optional external reference. Examples are membership number and employee number
          examples:
          - 123415A
        lastChangedAt:
          type: string
          description: When the contract was last changed
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        lastChangedBy:
          type: string
          description: Which client changed the contract last
          examples:
          - 123e4567-e89b-12d3-a456-426655440000
        loyaltyProgram:
          $ref: '#/components/schemas/LoyaltyProgramFlatResponse'
        orderLineEvents:
          type: array
          description: A list of order line events related to this contract
          items:
            $ref: '#/components/schemas/OrderLineEventResponse'
        organisationId:
          type: integer
          description: Which organisation the contract concerns
          format: int64
          examples:
          - 1
        parent:
          type: string
          description: If present, contract UUID of the parent contract. This field is usually set if the contract is created by a coupon usage, whereas this contract has a time constraint and the parent has a coupon constraint.
          examples:
          - fd29908d-a2ae-4fe0-8e10-7f0db437c554
        policies:
          type: array
          description: The list of keys validated against the customer claiming the contract
          items:
            $ref: '#/components/schemas/PolicyResponse'
        remainingCoupons:
          type: integer
          description: The remaining coupons for coupon based contracts. Derived from couponsLimit and orderLineEvents. The amount of remaining coupons are counted yearly and based of the earliest travel date.
          format: int64
        status:
          type: string
          description: 'The contract status. A normal contract has status valid. It can be expired, refunded, cancelled, misused and valid '
          examples:
          - Refunded
        subContracts:
          type: array
          description: If present, contains timed contracts that are dependent on this contract. See Contract response
          items:
            type: object
        transactions:
          type: array
          description: The list of transactions for this contract (earn/burn or giftcard)
          items:
            $ref: '#/components/schemas/TransactionResponse'
        uuid:
          type: string
          description: Unique contract identifier
          examples:
          - 123e4567-e89b-12d3-a456-426655440000
      description: A contract between a customer and an organisation
    ContractConsumerResponse:
      required:
      - createdAt
      - createdBy
      - customerNumber
      - customerOrganisationId
      - isBlocked
      - isContractHolder
      - lastChangedAt
      - lastChangedBy
      type: object
      properties:
        createdAt:
          type: string
          description: When the contract consumer was created
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        createdBy:
          type: string
          description: Which client created the contract consumer
          examples:
          - 123e4567-e89b-12d3-a456-426655440000
        customerNumber:
          type: integer
          description: The customer entitled to use the contract. Unique Entur specific number
          format: int64
          examples:
          - 122334
        customerOrganisationId:
          type: integer
          description: The organisation ID the customer belongs to
          format: int64
          examples:
          - 42
        customerRef:
          type: string
          description: The customer entitled to use the contract. External reference unique to organisation
          examples:
          - 073R41D4R
        isBlocked:
          type: boolean
          description: Marks that this specific user has been disallowed from using this contract by the contract owner
          examples:
          - true
        isContractHolder:
          type: boolean
          description: Marks that this specific user's organisation is the owner of the contract
        lastChangedAt:
          type: string
          description: When the contract consumer was last changed
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        lastChangedBy:
          type: string
          description: Which client changed the contract consumer last
          examples:
          - 123e4567-e89b-12d3-a456-426655440000
      description: A description of the customer that's allowed to use the contract
    ClaimContractResponse:
      required:
      - customerNumber
      - success
      type: object
      properties:
        customerNumber:
          type: integer
          description: The customerNumber for the customer now claiming the personnel ticket
          format: int64
          examples:
          - 1234567
        success:
          type: boolean
          description: Whether the claim was successful
      description: The response after claiming a contract
    TransactionResponse:
      required:
      - amount
      - currency
      - timestamp
      type: object
      properties:
        amount:
          pattern: -?\d*\.\d\d
          type: string
          description: 'How much was the amount changed by this transaction? Positive value means deposit onto the card, negative withdrawal. Example: -130.00'
        currency:
          type: string
          description: Currency used in this transaction. Only one currency is allowed for all transactions on a single contract.
          examples:
          - NOK
        email:
          type: string
          description: Identifying sellers email for this transaction.
          examples:
          - test@test.no
        externalTransactionId:
          type: string
          description: External transaction id for the ongoing transaction.
          examples:
          - 9087a885782a819f95816d88da8d78
        internalTransactionId:
          type: string
          description: Internal unique identifier for this transaction.
          examples:
          - 1927bd54-4cc4-4ea1-8431-599231f39797
        posId:
          type: integer
          description: Identifying point of sale for this transaction.
          format: int64
          examples:
          - 317001944
        rrn:
          type: string
          description: External RRN for the payment.
          examples:
          - 22ceb5c3acaf78a54f3af5de2050f0
        timestamp:
          type: string
          description: Timestamp for this transaction.
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
      description: The list of transactions for this contract (earn/burn or giftcard)
    LoyaltyProgramDescriptionResponse:
      required:
      - createdAt
      - createdBy
      - description
      - languageCode
      - lastChangedAt
      - lastChangedBy
      type: object
      properties:
        createdAt:
          type: string
          description: When the loyalty program was created
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        createdBy:
          type: string
          description: Which client created the loyalty program
          examples:
          - 123e4567-e89b-12d3-a456-426655440000
        description:
          type: string
          description: Loyalty program description. Supports any kind of text
          examples:
          - Reis Kundekort gir deg 20% rabatt på alle kjøp
        displayName:
          type: string
          description: Display name for loyalty program
          examples:
          - Reis Kundekort
        languageCode:
          type: string
          description: What language the description is written in, ISO639-3
          examples:
          - NOB
        lastChangedAt:
          type: string
          description: When the loyalty program was last changed
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        lastChangedBy:
          type: string
          description: Which client changed the loyalty program last
          examples:
          - 123e4567-e89b-12d3-a456-426655440000
      description: Description of a loyalty program version
    ErrorResponse:
      required:
      - correlationId
      - error
      - message
      - path
      - status
      - timestamp
      type: object
      properties:
        timestamp:
          type: string
          description: When the error occurred.
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        status:
          type: integer
          description: The http status code.
          format: int32
          examples:
          - 400
        errorCode:
          type: string
          description: Application specific error code
          examples:
          - '1033'
        error:
          type: string
          description: The http status reason.
          examples:
          - Bad request
        path:
          type: string
          description: The request URI.
          examples:
          - /loyaltyPrograms
        message:
          type: string
          description: The main error message.
          examples:
          - Validation failed for ...
        correlationId:
          type: string
          description: The unique correlation id for the request.
          examples:
          - b5d4960d-7ab2-43d6-a8f3-113da042a288
        errors:
          type: array
          description: Optional list of error specifications.
          items:
            $ref: '#/components/schemas/ErrorSpecification'
      description: Response object for errors occurring in the customers API
    PolicyResponse:
      required:
      - id
      - key
      type: object
      properties:
        id:
          type: integer
          description: Id of the policy
          format: int64
          examples:
          - 1
        key:
          type: string
          description: Key for which field that should be matching
          examples:
          - surname
      description: Policy, returns keys that have to match
    ErrorSpecification:
      required:
      - defaultMessage
      - field
      type: object
      properties:
        field:
          type: string
          description: The field of the associated object in the request related to the error.
        defaultMessage:
          type: string
          description: The message explaining why the error occurred.
        rejectedValues:
          type: object
          description: A list of rejected values.
      description: Optional list of error specifications.
    PageOfContractResponse:
      required:
      - items
      - totalItems
      - totalPages
      type: object
      properties:
        items:
          type: array
          description: All items for this page
          items:
            $ref: '#/components/schemas/ContractResponse'
        totalItems:
          type: integer
          description: Total items which could be returned
          format: int64
          examples:
          - 1
        totalPages:
          type: integer
          description: Total number of pages
          format: int64
          examples:
          - 1
      description: Paged content
    ClaimPersonnelTicketRequest:
      required:
      - customerNumber
      - externalReference
      type: object
      properties:
        externalReference:
          pattern: \w+-(\w+)+-\w+
          type: string
          description: The code of the personnel ticket to claim
          examples:
          - ABCD-EF12-3456-GH45
        customerNumber:
          type: integer
          description: The customerNumber referring to the customer who claims the personnel ticket
          format: int64
          examples:
          - 1234567
      description: A request for claiming a personnel ticket
    OrderLineReference:
      required:
      - orderId
      - orderLineId
      type: object
      properties:
        orderId:
          maxLength: 90
          minLength: 0
          type: string
          description: The Order id, used for lookup when trying to find the order in Enturs systems.
          examples:
          - ABCD
        orderLineId:
          maxLength: 100
          minLength: 0
          type: string
          description: The order line Id for Entur orders.
          examples:
          - ABCD
      description: The order line reference. This is used to check if consumption has already been validated.
    TaxDistributionResponse:
      required:
      - isUnknown
      - taxMonth
      - taxSaving
      - taxYear
      type: object
      properties:
        isUnknown:
          type: boolean
          description: If set, the tax distribution saving for that month is unknown. This is the case for all period tickets before may 2021. They need to be calculated manually
        taxMonth:
          type: integer
          description: The month of the tax saving
          format: int32
        taxSaving:
          type: string
          description: The value of tax saved
        taxYear:
          type: integer
          description: The year of the tax saving
          format: int32
      description: Tax distribution for an order line
    CouponConfigResponse:
      required:
      - defaultQuantity
      - loyaltyProgramId
      type: object
      properties:
        defaultQuantity:
          type: integer
          description: Default number of how many coupons can be used. May be overridden by contract coupon limit
          format: int64
        defaultStartTime:
          type: string
          description: The default start time of the contract created by a coupon usage. If set, the contract created by a coupon usage will start on the specified time of the travel date or when created
          format: time
        loyaltyProgramId:
          type: integer
          description: The loyalty program the contract created by the coupon is connected to
          format: int64
        usageValidityPeriod:
          type: string
          description: The duration of the of the contract created by a coupon usage. If set, the contract created by a coupon usage will set expiration date to the end of the duration. It will override loyalty program usageValidityPeriod
          format: duration
          examples:
          - P3DT12H30M5S
      description: Configuration for coupons. This is only set for loyalty program type COUPONS
    ContractConsumption:
      required:
      - contractUuid
      - customerNumber
      - entitlementProductId
      - firstTravelDate
      type: object
      properties:
        contractUuid:
          type: string
          description: The id of the contract consumed
          format: uuid
          examples:
          - cae8853a-583e-49af-be61-cf10875a541d
        coupons:
          type: integer
          description: The number of coupons consumed. Has no effect if the contract does not specify a number of available coupons. Defaults to 1.
          format: int64
          examples:
          - 1
        customerNumber:
          type: integer
          description: The customer attempting to consume the contract
          format: int64
          examples:
          - 123415
        entitlementProductId:
          minLength: 1
          type: string
          description: The id of the product consumed. This is on NetEX format and must match the product in use by the supplied contract.
          examples:
          - ENT:TravelRebate:A2
        entitlementProductVersion:
          type: string
          description: The version of the product consumed. This is on NetEX format and if supplied must match the product version in use by the supplied contract.
          examples:
          - ENT:Version:V1
        firstTravelDate:
          type: string
          description: The start date and time of travel.
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        lastTravelDate:
          type: string
          description: The end date and time of travel. Defaults to firstTravelDate if not provided.
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        orderLineReference:
          $ref: '#/components/schemas/OrderLineReference'
      description: Contract consumption details
    TotalAmount:
      required:
      - amount
      - calculatedAt
      - currency
      type: object
      properties:
        amount:
          minimum: 0.01
          pattern: -?\d*\.\d\d
          type: string
          description: 'Amount amount. Format: -?\d*\.\d\d  Examples: 123.34  1.00  34000.00'
        calculatedAt:
          type: string
          description: When the amount was calculated
          format: date-time
          readOnly: true
        currency:
          type: string
          description: Currency of the amount
          examples:
          - NOK
      description: The current total for this contract (earn/burn or giftcard)
    ValidateContractConsumptionResponse:
      required:
      - code
      - isValid
      - reason
      type: object
      properties:
        code:
          type: string
          description: A code pertaining to the reason for rejection, if any. Code 3101 = OK.
          examples:
          - '3101'
        isValid:
          type: boolean
          description: True if all consumptions were valid, otherwise false
        reason:
          type: string
          description: A short message detailing the reasoning behind the status.
          examples:
          - ok
      description: The result of a contract consumption validations
    ValidateContractConsumptionRequest:
      required:
      - consumptions
      type: object
      properties:
        consumptions:
          minItems: 1
          type: array
          description: A list of consumptions to verify
          items:
            $ref: '#/components/schemas/ContractConsumption'
      description: A request to validate the consumption of one or more product entitlements in an order
    OrderLineEventResponse:
      required:
      - eventType
      - isCancelled
      - isPurchased
      - orderId
      - orderLineId
      - orderLineVersion
      - organisationId
      - price
      - timestamp
      type: object
      properties:
        codespace:
          type: string
          description: Codespace
          examples:
          - ABC
        couponsUsed:
          type: integer
          description: How many coupons (usages) this event is using. This defaults to 1, but will be ignored if the contract in question does not use coupons.
          format: int64
          examples:
          - 1
        effectiveCancellationDate:
          type: string
          description: If set, the effective date for cancellation.
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        eventType:
          type: string
          description: The order line event type. Can be one of 'PURCHASE' or 'CANCELLATION'. PURCHASE is used when the order line event describe purchase of a travel using a contract (not the same as isPurchased). CANCELLATION is when the order line event is a cancellation (can be the same as isCancelled)
        isCancelled:
          type: boolean
          description: Whether the order line event is a cancellation
        isPurchased:
          type: boolean
          description: Whether the order line event describes the purchase of a contract, or contract consumer
        lastTravelDate:
          type: string
          description: The last date of travel, related to entitlement usage. Defaults to equal travelDate. Relevant for period tickets only.
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        manualTransactionComment:
          type: string
          description: If the order line is added manually, this field will have an explanation
          examples:
          - Refund because the order was cancelled too late
        orderId:
          type: string
          description: The order ID
          examples:
          - ABC
        orderLineId:
          type: string
          description: The order line ID
          examples:
          - KFN
        orderLineText:
          type: string
          description: The name of the product that this usage refers to. This should be supplied by the caller to indicate which item has been bought. This is displayed to the user in reports.
          examples:
          - 1 x Voksen, Oslo S - OSL
        orderLineVersion:
          type: string
          description: The order line version
          examples:
          - '132'
        organisationId:
          type: integer
          description: The organisation through which the order was placed
          format: int64
          examples:
          - 1
        originalPrice:
          type: string
          description: The original price for this item, i.e.  i.e the original price without the travellers discount.
          examples:
          - '3.77'
        price:
          type: string
          description: The actual paid price for this item, i.e. what did the user actually pay after rebate. Negative if this was a cancellation
          examples:
          - '3.77'
        taxDistributions:
          type: array
          description: Tax savings for this order line
          items:
            $ref: '#/components/schemas/TaxDistributionResponse'
        timestamp:
          type: string
          description: When the order line event was saved
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
        travelDate:
          type: string
          description: The first date of travel on this ticket. Will be used to decide when to report this usage to the Norwegian tax administration, if applicable. Defaults to the current date and time.
          format: date-time
          examples:
          - '2007-12-03T10:15:30+01:00'
      description: An order line event on a contract
  responses:
    Error400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Error401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Error500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Error403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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-personnel-tickets-openapi.json
- entur-personnel-tickets-openapi.yml