Entur Incoming Settlements API
Create and manage settlements to be cleared by CLEOS
Create and manage settlements to be cleared by CLEOS
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/entur:entur-incoming-settlements-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Clearing Incoming Settlements API
description: Partner API documentation for self serviced use of the Clearing services. See the developer guide for more information.
contact:
name: Team Avregning
version: 2026.09.1
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
/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
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
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
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
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
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
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
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.
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
parameters:
ET-Client-Name:
name: ET-Client-Name
in: header
description: 'Entur Client Header.
It is required that all consumers identify themselves by using this header.
Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers.
The structure of ET-Client-Name should be: `<company>-<application>`.'
required: false
style: simple
explode: false
schema:
type: string
X-Correlation-Id:
name: X-Correlation-Id
in: header
description: Correlation id
required: false
style: simple
explode: false
schema:
type: string
securitySchemes:
bearerToken:
type: http
scheme: bearer
bearerFormat: JWT
externalDocs:
description: Clearing Partner API Developer Guide
url: https://developer.entur.no/guides/clearing