# Get started with settlements

This guide shows how to submit Generic Settlements for clearing as a partner. The process has three
steps: **Authentication**, **Submission** (POST a settlement for clearing), and **Status** (check
the settlement's status).

:::warning
Settlement clearing is a complex topic requiring solid understanding of accounting principles, VAT regulations,
business requirements, and configuration of the Clearing system.
 
This guide enables developers to submit Generic Settlements but does not cover the full scope of settlement
clearing. Developers must collaborate closely with the Chart of Accounts administrator to ensure proper
modelling of the data to be cleared.
:::

:::note
See [Authentication](/docs/authentication#partner-services) for how your organisation gets onboarded
and how to create a client to call the API.

Please refer to the [Generic Settlements API documentation](/apis/clearing) for the full endpoint
reference — this guide focuses on example use, not exhaustive request/response schemas. See
[Generic Settlements](/docs/partner-services/clearing/generic-settlements) for the underlying concepts.
:::

## Minimal settlement

This is the minimal required structure to perform a successful clearing of an (empty) settlement:

```json
{
  "distributionChannelRef": "ENT:DistributionChannel:ExternalPSP",
  "posRef": "EOS:Pos:ExternalPSP",
  "settlementDate": "2025-11-26",
  "settlementNo": 1,
  "genericTransactions": []
}
```

::endpoint[clearing/importGenericSettlement]

Submitting it returns a response similar to this:

```json
{
  "id": 111122222,
  "posRef": "EOS:Pos:ExternalPSP",
  "settlementDate": "2025-11-26",
  "settlementNo": 1,
  "externalSettlementNo": 1,
  "ignoreSequence": false,
  "comments": [],
  "status": 0,
  "statusDescription": "Partner Settlement queued for processing."
}
```

This means that the Clearing system has accepted the settlement for processing, and put it in queue to be cleared asynchronously.
Since no annexes are defined, the clearing will not generate any accounting entries and has therefore little purpose for a partner.
See [Submit an advance settlement](/guides/clearing/submit-advance-settlement) for an example with annexes.

It might take some time before the clearing is fully processed. You can check the status with the
returned `id`:

::endpoint[clearing/getSettlementImport]

```json
{
  "id": 11111222222,
  "posRef": "EOS:Pos:ExternalPSP",
  "settlementDate": "2025-11-26",
  "settlementNo": 1,
  "externalSettlementNo": 1,
  "ignoreSequence": false,
  "comments": [],
  "status": 1,
  "statusDescription": "100M-Mottakskontroll av oppgjør id=11111222222,ENT:Pos:OsloS1,onr=1,date=25.11.2025,priority=2,batchId=1763981079206 påbegynt 2025-11-25T11:44:39.274030841.\n..."
}
```

## Important to remember

- The `settlementNo` must be sequentially incremented by 1 per settlement, and the combination of `settlementNo` and `posRef` must be unique.
Keeping track of settlement numbers is the responsibility of the partner.

- It's worth noting that if previous settlements fail, or if settlements become out of sequence, subsequent settlements will
not be processed until all previous settlements are successfully cleared.

- Once a settlement is cleared, it cannot be modified or deleted. Any corrections must be submitted through new settlements —
see [Submit a correction or refund](/guides/clearing/submit-a-correction).

- The definition of `settlementDate` is partially up to the partner. This could for example be the date the sale was made
or the date the settlement is uploaded to the Clearing system. However, it's worth noting that setting it to a future date can delay
the clearing process if it happens to fall outside the current calendar month.

- Comments are supposed to be short and relevant to the settlement/clearing.

## Resubmitting settlements

The Clearing system supports settlement resubmission using the same `posRef` and `settlementNumber` combination. If a settlement with 
matching identifiers has already been successfully received, the resubmission will be rejected to prevent duplicate 
processing.

**Client responsibilities:**
- Generate sequential settlement numbers for each settlement submission
- Implement retry logic to resubmit failed settlements (within reasonable limits)

Note that the duplicate detection mechanism is limited to settlements submitted within the last 7 days, it is
only intended to handle transient submission failures. Older duplicates will be detected and failed during clearing.

**Key point:** Settlement identifiers (`posRef` + `settlementNumber`) must be unique and sequential. Resubmit failed 
settlements using the same identifiers; do not create new settlement numbers for retry attempts.

## High transaction volumes

The Clearing system can process large volumes of transactions efficiently. However, the Generic Settlement API is optimized for 
moderate-sized settlements rather than bulk processing.

Submitting settlements containing thousands of transactions and multi-megabyte JSON payloads introduces reliability and 
performance risks. Instead, distribute high-volume transaction data across multiple smaller settlements submitted at 
regular intervals.

For scenarios requiring continuous high-volume processing, a streaming-based integration module may be more appropriate.
This capability will be developed based on identified use cases.

**Key point:** Split high-volume transaction data into multiple smaller settlements.