Entur Incoming Settlements API

openapi: 3.2.0
info:
  title: Entur Incoming Settlements API
  version: 2026.09.1
  contact:
    name: Team Avregning
  description: 'Operations tagged Incoming Settlements across 2 of this provider''s published API definitions: entur-clearing-openapi.json, entur-clearing-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.entur.io/clearing
- url: https://api.staging.entur.io/clearing
- url: https://api.dev.entur.io/clearing
security:
- bearerToken: []
tags:
- name: Incoming Settlements
  description: Create and manage settlements to be cleared by CLEOS
paths:
  /v1/settlement-import/generic:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    post:
      tags:
      - Incoming Settlements
      summary: Submit a Generic Settlement for asynchronous clearing.
      description: Creates a GenericSettlementImport, in queue for for clearing. Use the returned result for further queries based on the assigned ID
      operationId: importGenericSettlement
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerSettlementImportDto'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerSettlementImportResponseDto'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '403':
          description: No access to settlement
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '409':
          description: Conflict due to business rules, eg duplicate settlement
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
      x-entur-permissions:
        value: cleos-settlements:opprett
    servers:
    - url: https://api.entur.io/clearing
    - url: https://api.staging.entur.io/clearing
    - url: https://api.dev.entur.io/clearing
  /v1/settlement-import/{id}:
    parameters:
    - $ref: '#/components/parameters/ET-Client-Name'
    - $ref: '#/components/parameters/X-Correlation-Id'
    get:
      tags:
      - Incoming Settlements
      summary: Get a settlement by id
      description: Get the details of a settlement to see its status or any errors that occurred during clearing.
      operationId: getSettlementImport
      parameters:
      - name: id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerSettlementImportResponseDto'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '403':
          description: No access to incoming settlement
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '404':
          description: Incoming settlement not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/CleosProblemJsonDto'
      x-entur-permissions:
        value: cleos-settlements:opprett
    servers:
    - url: https://api.entur.io/clearing
    - url: https://api.staging.entur.io/clearing
    - url: https://api.dev.entur.io/clearing
components:
  schemas:
    PartnerTransactionImportDto:
      type: object
      description: A transaction to be cleared, represented in a generic format suitable for various transaction types.
      properties:
        transactionType:
          type: string
          description: Type of the transaction being submitted for clearing. This type MUST be assigned to the relevant Chart Of Accounts by the Cleos Administrator first.
          example: ACMSALE
          maxLength: 30
          minLength: 0
        orderId:
          type: string
          description: OrderID is a unique identifier for the transaction within the Partner's system. It is used to track and manage the transaction throughout its lifecycle. Note that several transactions may refer to the same OrderID (eg both the sale and the payment transaction)
          example: ORD123456
          maxLength: 50
          minLength: 0
        orderVersion:
          type: integer
          format: int32
          description: OrderVersion is a sequential version number for the transaction. It is used to track changes to the transaction over time.
          example: 1
        genericAnnexes:
          type: array
          description: The Annexes to be cleared. A transaction must carry at least one — a transaction with nothing to clear should be left out of the settlement entirely. A settlement covering a period with no sales is submitted with an empty genericTransactions list instead.
          items:
            $ref: '#/components/schemas/PartnerAnnexDto'
          minItems: 1
      required:
      - genericAnnexes
      - transactionType
    PartnerSettlementImportResponseDto:
      type: object
      description: Relevant information on the successfully registered Settlement Import. See documentation for PartnerSettlementImportDto for details on fields that the client submitted.
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of queued Settlement Import.
          example: 12345
        posRef:
          type: string
        settlementDate:
          type: string
          format: date
        settlementNo:
          type: integer
          format: int64
        correctedSettlementId:
          type: integer
          format: int64
        externalSettlementNo:
          type: integer
          format: int64
        ignoreSequence:
          type: boolean
          description: Indicates whether sequence errors will be ignored during import, typical for negative settlement sequences (corrections).
          example: false
        comments:
          type: array
          items:
            type: string
        status:
          type: integer
          format: int32
          description: Status code indicating the result of the import operation. This will always be 0 (TO BE PROCESSED) on creation. 1 indicates SUCCESSFUL CLEARING
          examples:
          - '0'
        statusDescription:
          type: string
          description: Message providing additional information on the import status.
          example: Partner Settlement queued for processing.
    PartnerMoneyDto:
      type: object
      description: Representation of an amount with relevant metadata such as currency and tax information. The Annex will be considered without Price Contribution if amount is 0.00
      properties:
        amount:
          type: string
          description: The monetary amount in a 12.2 format (up to 12 digits before decimal, exactly 2 after). May be negative, for a discount or a refund.
          example: '"12345.34"'
          pattern: ^-?\d{1,12}\.\d{2}$
        currency:
          type: string
          description: The currency of the amount in ISO 4217 format. Default NOK if not provided
          example: NOK
        taxCode:
          type: string
          description: The standard tax code applicable to the amount, if any
          example: '"25"'
        localTaxCode:
          type: string
          description: 'The local tax code applicable to the amount, if any. NOTE: This is normally not necessary to set but may be relevant in scenarios where the tax rate for a code changes'
          example: 25A
        taxRate:
          type: string
          description: 'The tax rate applicable to the amount, if any. NOTE: This must be consistent with the CLEOS configuration for the Tax Code (SEGMENT7)'
          example: '"12.00"'
          pattern: ^\d{1,2}(\.\d{1,2})?$
        weight:
          type: string
          description: The weight associated with the amount, if any, in a 12.4 format (up to 12 digits before decimal, optionally followed by 1-4 after). Thw weight is used for proportional clearing based a custom weight instead of PriceContributions. For example representing distance or time.
          example: '"1500.1234"'
          pattern: ^\d{1,12}(\.\d{1,4})?$
      required:
      - amount
    PartnerCommentDto:
      type: object
      description: Any external comments relevant for clearing the settlement. This will not be part of the reporting context. Useful for guiding potential corrections.
      properties:
        comment:
          type: string
          maxLength: 500
          minLength: 0
      required:
      - comment
    PartnerRefDto:
      type: object
      description: A REF is a reference that is intended for business logic use, with best effort NAME lookups in GUI and reporting. For most practical purposes it can be considered a URN on the format NAMESPACE:TYPE:ID, but this is not guaranteed.
      properties:
        id:
          type: string
          maxLength: 100
          minLength: 0
        name:
          type: string
          description: 'The NAME corresponding to the REF, if found in the CLEOS REF lookup table (best effort). NOTE: This may be set for REFs returned by CLEOS, the client is not expected to submit this value.'
      required:
      - id
    CleosProblemJsonDto:
      type: object
      description: DTO representing the generic response of an error condition according to the JSON+ERROR content type (RFC 9457).
      properties:
        type:
          type: string
          format: uri
          description: 'URI identifying the type of problem. NOTE: type about:blank may still be used for general errors.'
          enum:
          - about:blank
          - urn:problem-type:cleos-default
          - urn:problem-type:cleos-ref
          example: urn:problem-type:cleos-default
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
          format: uri
          description: Absolute URI to the the resource causing the error. Note that this is technically not a reference to the persistent error _instance_, but still useful default behaviour.
          example: https://api.entur.io/clearing/v1/resource/123
        properties:
          type: object
          additionalProperties: {}
        timestamp:
          type: string
          format: date-time
          description: Server side timestamp of incident, used by cleos problem-types
          example: '2024-06-17T12:35:53.932Z'
        correlationId:
          type: string
          description: Correlation ID for tracking the error, used by cleos problem-types. Typically based on the request header X-Correlation-Id
          example: 1234-ABCDEFG-5678-HIJKL-91011-MNOPQ
        domainRefs:
          type: array
          description: 'Domain object references that caused the error on problem type cleos-ref. NOTE: These _may_ be references to entities outside of CLEOS'
          items:
            $ref: '#/components/schemas/PartnerRefDto'
            description: 'Domain object references that caused the error on problem type cleos-ref. NOTE: These _may_ be references to entities outside of CLEOS'
            example: EOS:Agreement:1234
    PartnerSettlementImportDto:
      type: object
      description: Generic Settlement submitted by Partner. This is a subset of the CLEOS settlement structure intended for self-serviced clearing.
      properties:
        msgSubjectId:
          type: string
        id:
          type: integer
          format: int64
        posRef:
          type: string
          description: Reference to the PointOfSale (POS) for which the settlement is created.
          maxLength: 100
          minLength: 0
        distributionChannelRef:
          type: string
          description: Reference to the Distribution Channel for which the settlement is created.
          maxLength: 100
          minLength: 0
        settlementDate:
          type: string
          format: date
          description: Settlement Date for the settlement on the format YYYY.MM.DD
        settlementNo:
          type: integer
          format: int64
          description: 'Settlement Sequence Number. This must be a continuous sequence for the settlement not to fail clearing. Negative sequences are typically used for corrections that are out of sequence. If not specified, the next number in a negative sequence will automatically be assigned based previous correction on the same POS. '
        correctionForSmntId:
          type: integer
          format: int64
          description: If this settlement is a correction of a previous settlement, the internal CLEOS ID of the settlement being corrected must be provided.
        externalSettlementNo:
          type: integer
          format: int64
          description: External Settlement Number provided by the Partner. If not provided, the settlementNo will be used as external reference as well.
        comments:
          type: array
          description: Optional comments associated with the settlement. Used for audit trail and additional information relevant for clearing.
          items:
            $ref: '#/components/schemas/PartnerCommentDto'
        genericTransactions:
          type: array
          description: 'List of Generic Transactions associated with the settlement. The list is required but may be empty: a period with no sales still consumes its Settlement Number, and submitting the empty Settlement keeps the sequence unbroken for the next one.'
          items:
            $ref: '#/components/schemas/PartnerTransactionImportDto'
        context:
          type: object
          additionalProperties: {}
          description: Context map containing additional key-value pairs relevant for the settlement. Only simple key-value pairs are supported (String, Number, Boolean) with a max length of 100 characters per value.
      required:
      - distributionChannelRef
      - genericTransactions
      - posRef
      - settlementDate
    PartnerAnnexDto:
      type: object
      description: Generic representation of a node in a recursive transaction tree structure.
      properties:
        cancel:
          type: boolean
          description: If true, this annex root (and all sub-annexes) will be accounted with DEBED/CREDIT switched. Typically used for reversing older versions of the transaction. Default false.
        guid:
          type: string
          maxLength: 38
          minLength: 0
        annexRef:
          type: string
          maxLength: 100
          minLength: 0
        attributes:
          type: object
          additionalProperties:
            type: string
        price:
          $ref: '#/components/schemas/PartnerMoneyDto'
          description: PriceContribution may be provided if a custom weight on Price is needed. The Amount will always be recalculated as the sum of PriceContributions.
        priceContribution:
          $ref: '#/components/schemas/PartnerMoneyDto'
        foreignAmount:
          $ref: '#/components/schemas/PartnerMoneyDto'
        description:
          type: string
          maxLength: 500
          minLength: 0
        context:
          type: object
          additionalProperties: {}
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/PartnerAnnexDto'
        subAnnexes:
          type: array
          items:
            $ref: '#/components/schemas/PartnerAnnexDto'
      required:
      - annexRef
      - priceContribution
  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:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Clearing Partner API Developer Guide
  url: https://developer.entur.no/guides/clearing
x-refined-from:
- entur-clearing-openapi.json
- entur-clearing-openapi.yml