---
title: "Overview"
description: "The API settles the commission after a transaction closes successfully and makes the invoice available as a PDF."
url: "https://real-estate-agency.apim.eu/apis/commission-settlement/docs/overview"
image: "https://real-estate-agency.apim.eu/_og/d/c_Ocean.takumi,title_Overview,description_The+API+settles+the+commission+after+a+transaction+closes+successfully+and+makes+the+invoice+available+as+a+PDF.,props_eyJ0aGVtZSI6eyJtb2RlIjoiZGFyayIsImNvbG9ycyI6eyJwcmltYXJ5IjoiI0IwMjZGRiJ9fX0,p_Ii9hcGlzL2NvbW1pc3Npb24tc2V0dGxlbWVudC9kb2NzL292ZXJ2aWV3Ig,s_C9b00lRyx_fadV6X.png"
---

# Overview

The API settles the commission after a transaction closes successfully and makes the invoice available as a PDF.

## [Split commission](#split-commission)

For a regulated consumer transaction - such as the sale of an apartment or single-family home to a consumer - the buyer's share must not exceed the seller's share. The API validates this when a settlement is created and otherwise responds with `422` and `code: "commission_not_permitted"`.

Check the same condition already on the property record - that's where the commission advertised in the listing lives. A settlement that deviates from the advertised commission is hard to defend in a dispute.

## [Assessment basis](#assessment-basis)

| Deal type         | Basis                                          |
| :---------------- | :--------------------------------------------- |
| sale              | notarized purchase price                       |
| rental            | net cold rent, usually expressed as a multiple |
| commercial_rental | annual net cold rent                           |

## [Payments](#payments)

`POST /settlements/{id}/payments` also records partial payments. The status only moves to `paid` once the sum of payments reaches the gross amount; until then it stays `partially_paid`. That keeps what's outstanding visible without extra accounting logic.

## [Upfront calculation](#upfront-calculation)

`POST /commission/calculator` runs a commission calculation without creating anything. That's the right call for sales conversations and for the commission figure shown in the listing.

## [Required scope](#required-scope)

All calls require `commissions:read`. Write operations are deliberately bound to the same role, because settlements should only ever be created by accounting.