Overview
The API settles the commission after a transaction closes successfully and makes the invoice available as a PDF.
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
| Deal type | Basis |
|---|---|
sale | notarized purchase price |
rental | net cold rent, usually expressed as a multiple |
commercial_rental | annual net cold rent |
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
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
All calls require commissions:read. Write operations are deliberately bound to the same role, because settlements should only ever be created by accounting.