> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engrate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Clearing & Settlement Flow

> How MaBiS settlement works — from schedule submission through clearing to final billing

This guide explains the MaBiS settlement process end-to-end. It covers what happens after schedules are submitted, how clearing works, and what your integration needs to handle at each phase.

## What is MaBiS?

MaBiS (Marktregeln für die Durchführung der Bilanzkreisabrechnung Strom) is the German framework governing how balance responsible parties (BRPs) settle their energy accounts with Transmission System Operators (TSOs). It defines the rules for measuring what actually happened on the grid, comparing it to what was declared in schedules, and settling any differences.

The Settlement Management API implements this process, handling EDIFACT message exchange (MSCONS, PRICAT, UTILMD, IFTSTA) and providing structured access to clearing data.

## The clearing cycle

Each settlement month goes through a structured process with deadlines calculated in working days (Werktage) after month end:

```mermaid theme={null}
%%{init: {'theme': 'base'}}%%
flowchart TD
    subgraph month["Settlement Month"]
        schedules["Schedules submitted\n(via Schedule Management API)"]
        metering["Metering data collected\n(physical meters)"]
    end

    subgraph erst["Erstaufschlag (M+10–12 WT)"]
        bg_szr["BG-SZR published\nBalance group summaries"]
        bk_szr["BK-SZR published\nBalance circle summaries"]
    end

    subgraph clearing["Clearing Phase (M+11–30 WT)"]
        mscons["MSCONS received\nSettlement interval data"]
        pricat["PRICAT received\nreBAP prices"]
        prelim["Preliminary billing\n(M+18 WT)"]
    end

    subgraph objection_phase["Objection Window (M+18–30 WT)"]
        review["Review settlement data"]
        object["File objections\nif data is disputed"]
    end

    subgraph final_phase["Final Settlement (M+42 WT)"]
        final["Final billing issued"]
        closed["Period closed"]
    end

    month --> erst
    erst --> clearing
    clearing --> objection_phase
    objection_phase --> final_phase
```

### Key milestones

| Milestone           | Timing          | What happens                                               |
| ------------------- | --------------- | ---------------------------------------------------------- |
| Erstaufschlag       | M+10/12 WT      | First aggregation summaries (SZR) are published by the TSO |
| Clearing start      | M+11/13 WT      | TSO/DSO begin sending MSCONS settlement data               |
| Preliminary billing | M+18 WT         | First complete settlement figures available                |
| Objection window    | M+18 to M+30 WT | BRPs can file objections against disputed values           |
| Final billing       | M+42 WT         | Definitive settlement — no further changes                 |

Use `GET /mabis/clearing-calendar` to compute exact dates for any settlement month.

## Settlement flow

### 1. Create a clearing period

Before receiving settlement data, create a [Clearing Period](/api-reference/settlement-management/models/clearing-period) for the balance group and month:

```
POST /mabis/clearing-periods
{
  "bilanzkreis_eic": "11XEXAMPLE-BKV-A",
  "bilanzierungsmonat": "2026-01-01"
}
```

The platform computes MaBiS deadlines automatically based on the clearing calendar.

### 2. Receive settlement data

As MSCONS messages arrive from the TSO/DSO, the platform parses them and stores daily [Clearing Settlement](/api-reference/settlement-management/models/clearing-settlement) records. Each record contains raw interval values for one day.

Track message flow via `GET /mabis/clearing-periods/{uid}/messages` — you'll see MSCONS (metering data), PRICAT (prices), UTILMD (registrations), and IFTSTA (status reports).

### 3. Review and calculate imbalance

Once settlement data is available, calculate the [Imbalance](/api-reference/settlement-management/models/imbalance) for the clearing period:

```
GET /mabis/clearing-periods/{uid}/imbalance
```

This compares your scheduled energy against actual metered energy for each day, applies reBAP [Control Energy Prices](/api-reference/settlement-management/models/control-energy-price), and returns the total financial impact.

### 4. File objections if needed

If settlement values are wrong, file an [Objection](/api-reference/settlement-management/models/objection) within the objection window (M+18 to M+30 WT):

```
POST /mabis/clearing-periods/{uid}/objections
{
  "objection_type": "volume",
  "disputed_values": {
    "date": "2026-01-15",
    "interval": 42,
    "our_value_mwh": 1.5,
    "tso_value_mwh": 1.8
  },
  "reason": "Metering data does not match our records"
}
```

The TSO will respond with acceptance or rejection via UTILMD.

### 5. Validate before deadline

Before each deadline, validate data completeness:

```
GET /mabis/clearing-periods/{uid}/validate
```

This checks that all expected settlement days have data, message counts are consistent, and no data gaps exist.

## Imbalance calculation

Imbalance is the core financial metric in MaBiS settlement. It represents the difference between what you declared (scheduled) and what actually happened (metered).

**Per interval:**

```
imbalance = actual_energy - scheduled_energy
```

**Financial impact:**

```
cost = imbalance × reBAP_price
```

A positive imbalance means actual exceeded scheduled (more consumption or less generation than declared) — you buy the difference at the reBAP price. A negative imbalance means scheduled exceeded actual — you sell the surplus at the reBAP price.

The reBAP is a uniform price across all control areas (regelzonenübergreifend), updated quarter-hourly. It can be significantly higher or lower than market prices, creating a strong incentive for accurate scheduling.

## Aggregation objects

[Aggregation objects](/api-reference/settlement-management/models/aggregation-object) (MaBiS-Zaehlpunkte) are virtual metering points that group physical meters for settlement purposes. They bridge the gap between physical metering infrastructure and the abstract balance group structure used for settlement.

Each aggregation object has:

* A **type** (BAS, FPE, FPI, SLP, RLM) defining what kind of energy data it aggregates
* A **TSO area** and **DSO** linking it to the grid topology
* A **balance group EIC** associating it with your Bilanzkreis
* A **validity period** defining when the registration is active

The API receives aggregation object registrations via UTILMD messages and exposes them through `GET /mabis/aggregation-objects`.

## The clearing calendar

MaBiS deadlines are based on working days — weekends and German public holidays are excluded. This makes exact deadline computation non-trivial. The clearing calendar endpoint handles this:

```
GET /mabis/clearing-calendar?bilanzierungsmonat=2026-01-01
```

The response includes all phase boundaries and the `current_phase` field indicating where the month currently stands in the process. See [Clearing Calendar](/api-reference/settlement-management/models/clearing-calendar) for the full field reference.

## Monthly summary

For a consolidated view of energy and costs per aggregation object, use the monthly summary:

```
GET /mabis/energy-volumes/{mabis_zp_id}/monthly-summary
```

This combines [Energy Volume](/api-reference/settlement-management/models/energy-volume) data with [Control Energy Price](/api-reference/settlement-management/models/control-energy-price) data to produce a [Monthly Summary](/api-reference/settlement-management/models/monthly-summary) with total energy, total cost, and average price.

<Tip>
  See the [Settlement Management API Overview](/api-reference/settlement-management/overview) for a quick reference of all endpoints and the clearing lifecycle diagram.
</Tip>