---
title: "Commission Settlement"
url: "https://real-estate-agency.apim.eu/apis/commission-settlement/versions/6ae2ea20-d101-452a-9066-4c9c4d7d5fdc"
---

# Commission Settlement

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Commission Settlement","version":"1.0.0","description":"Settles the commission after a transaction closes successfully: create a\nsettlement, retrieve the invoice, record incoming payments.\n\nThe commission arises once the main contract is concluded. For a regulated\nconsumer transaction - such as the sale of an apartment or single-family home\nto a consumer - a split-commission principle typically applies, requiring the\nbuyer's share not to exceed the seller's share. The API validates the split\nwhen a settlement is created.\n","contact":{"name":"API Support - Real Estate Agency","email":"api-support@realestateagency.example"}},"servers":[{"url":"https://api.realestateagency.example/v1","description":"Production"},{"url":"https://sandbox.api.realestateagency.example/v1","description":"Sandbox"}],"tags":[{"name":"Settlements"},{"name":"Invoices"},{"name":"Commission"}],"security":[{"apiKey":[]}],"paths":{"/settlements":{"get":{"tags":["Settlements"],"summary":"List settlements","operationId":"listSettlements","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/SettlementStatus"}},{"name":"property_id","in":"query","schema":{"type":"string","example":"prop_8f2c1a"}},{"name":"period_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"period_to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Results list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Settlement"}},"page":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"tags":["Settlements"],"summary":"Create a settlement","description":"Creates the settlement for a completed transaction. The basis is the\nnotarized purchase price, or the agreed rent.\n","operationId":"createSettlement","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementCreate"},"example":{"property_id":"prop_8f2c1a","deal_type":"sale","assessment_basis_eur":645000,"buyer_percent":3.57,"seller_percent":3.57,"contract_date":"2026-08-14","buyer":{"name":"Anna Bergman","prospect_id":"lead_71ab"}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settlement"},"example":{"id":"stl_7c53","property_id":"prop_8f2c1a","status":"open","deal_type":"sale","assessment_basis_eur":645000,"line_items":[{"party":"buyer","rate_percent":3.57,"net_eur":19353.36,"tax_eur":3677.14,"gross_eur":23030.5},{"party":"seller","rate_percent":3.57,"net_eur":19353.36,"tax_eur":3677.14,"gross_eur":23030.5}],"due_date":"2026-08-28"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/NotAuthenticated"},"422":{"description":"Commission split not permitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"commission_not_permitted","message":"The buyer's share must not exceed the seller's share.","details":[{"field":"buyer_percent","reason":"exceeds_seller"}]}}}}}}},"/settlements/{settlementId}":{"parameters":[{"name":"settlementId","in":"path","required":true,"schema":{"type":"string","example":"stl_7c53"}}],"get":{"tags":["Settlements"],"summary":"Retrieve a settlement","operationId":"getSettlement","responses":{"200":{"description":"Settlement","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settlement"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/settlements/{settlementId}/payments":{"parameters":[{"name":"settlementId","in":"path","required":true,"schema":{"type":"string","example":"stl_7c53"}}],"post":{"tags":["Settlements"],"summary":"Record a payment","description":"Partial payments are allowed; the status only moves to `paid` once the balance is settled in full.","operationId":"recordPayment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_eur","value_date"],"properties":{"amount_eur":{"type":"number","format":"float","example":23030.5},"value_date":{"type":"string","format":"date","example":"2026-08-26"},"reference":{"type":"string","example":"INV-2026-0418"}}}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settlement"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/invoices/{invoiceId}/pdf":{"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","example":"inv_a920"}}],"get":{"tags":["Invoices"],"summary":"Download an invoice as PDF","operationId":"downloadInvoicePdf","responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/commission/calculator":{"post":{"tags":["Commission"],"summary":"Calculate a commission upfront","description":"Runs a commission calculation without creating a settlement - useful for\nsales conversations and for the figure shown in the listing.\n","operationId":"calculateCommission","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assessment_basis_eur","buyer_percent"],"properties":{"assessment_basis_eur":{"type":"integer","example":645000},"buyer_percent":{"type":"number","format":"float","example":3.57},"seller_percent":{"type":"number","format":"float","example":3.57},"tax_percent":{"type":"number","format":"float","default":19}}}}}},"responses":{"200":{"description":"Calculation","content":{"application/json":{"schema":{"type":"object","properties":{"line_items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"gross_total_eur":{"type":"number","format":"float","example":46061}}}}}},"400":{"$ref":"#/components/responses/ValidationError"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Every call carries an API key in the `apikey` header. You generate the\nkey in the Real Estate portal under \"My Apps\"; it's shown exactly once.\n\nEach key has the scopes it's allowed to use attached to it. If one is\nmissing, the API responds with `403` and `code: \"scope_missing\"`; the\nmissing scope is in `details[].field`.\n"}},"responses":{"NotAuthenticated":{"description":"Key is missing, revoked or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The request doesn't match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Page":{"type":"object","description":"Cursor-based pagination.","properties":{"count":{"type":"integer","example":25},"total":{"type":"integer","example":138},"next_cursor":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","example":"buyer_percent"},"reason":{"type":"string","example":"missing"}}},"Error":{"type":"object","description":"Uniform error format across all Real Estate Agency APIs.","required":["code","message"],"properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string","example":"The assessment basis is required to calculate the commission."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"SettlementStatus":{"type":"string","enum":["draft","open","partially_paid","paid","canceled"],"example":"open"},"DealType":{"type":"string","enum":["sale","rental","commercial_rental"],"example":"sale"},"Party":{"type":"object","properties":{"name":{"type":"string","example":"Anna Bergman"},"prospect_id":{"type":"string","example":"lead_71ab"},"address":{"type":"string","example":"148 Elm Street, 10001 Springfield"}}},"LineItem":{"type":"object","properties":{"party":{"type":"string","enum":["buyer","seller","tenant","landlord"]},"rate_percent":{"type":"number","format":"float","example":3.57},"net_eur":{"type":"number","format":"float","example":19353.36},"tax_eur":{"type":"number","format":"float","example":3677.14},"gross_eur":{"type":"number","format":"float","example":23030.5}}},"SettlementCreate":{"type":"object","required":["property_id","deal_type","assessment_basis_eur","buyer_percent","contract_date"],"properties":{"property_id":{"type":"string","example":"prop_8f2c1a"},"deal_type":{"$ref":"#/components/schemas/DealType"},"assessment_basis_eur":{"type":"integer","description":"Notarized purchase price, or annual net cold rent.","example":645000},"buyer_percent":{"type":"number","format":"float","example":3.57},"seller_percent":{"type":"number","format":"float","example":3.57},"contract_date":{"type":"string","format":"date","example":"2026-08-14"},"buyer":{"$ref":"#/components/schemas/Party"},"seller":{"$ref":"#/components/schemas/Party"}}},"Settlement":{"type":"object","properties":{"id":{"type":"string","example":"stl_7c53"},"property_id":{"type":"string","example":"prop_8f2c1a"},"status":{"$ref":"#/components/schemas/SettlementStatus"},"deal_type":{"$ref":"#/components/schemas/DealType"},"assessment_basis_eur":{"type":"integer","example":645000},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"invoice_id":{"type":"string","example":"inv_a920"},"due_date":{"type":"string","format":"date","example":"2026-08-28"},"paid_eur":{"type":"number","format":"float","example":0},"created_at":{"type":"string","format":"date-time","example":"2026-08-15T07:30:00Z"}}}}}}
```