Copy page

Settlements

Status: Roadmap. The conceptual model is documented here. Public REST endpoints described below are not yet wired into the API router (no handler is registered for these paths). The page describes the planned shape; treat any code samples as illustrative pending implementation.

A settlement rolls a group of invoices and credit notes into a single payout statement. Used for marketplace flows (paying sellers their share of platform revenue), reseller agreements (commissions on referred customers), and any scenario where money needs to flow back out based on aggregated billing activity.

Why this matters. Marketplace and reseller economics depend on getting payouts right - both the math and the audit trail - and most platforms accumulate this in spreadsheets and bespoke scripts that don't survive the next round of growth. Kontorion's settlement engine aggregates invoices, credit notes, and adjustments per counterparty, applies configurable commission and withholding rules, and produces both the partner-facing statement and the internal reconciliation record in one pass. The same flow supports a B2B marketplace paying out merchants weekly, a referral partner program issuing monthly commissions, a SaaS reseller channel netting platform fees against subscription revenue, and a content platform splitting subscription dollars across creators by consumption share.

Anatomy

Object	Purpose
Settlement	The header: counterparty, period, currency, totals, payout status.
SettlementLine	One row per source document (invoice, credit note, fee adjustment) included in the settlement.

Lifecycle

Code
draft  →  generated  →  finalized  →  payout_recorded

State	Meaning
draft	Manually created shell; lines being assembled
generated	The settlement runner produced this from a period's qualifying activity
finalized	Locked, totals frozen, ready for payout
payout_recorded	A payout reference (bank transfer, gateway transfer) is attached

Webhooks: settlement.generated, settlement.finalized, settlement.payout_recorded.

Generating a settlement

The settlement runner produces one settlement per (counterparty, period) based on rules configured per counterparty:

Code
curl -X POST /v1/settlements/generate \
  -d '{
    "counterparty_id": "partner_xyz",
    "period_start": "2025-03-01T00:00:00Z",
    "period_end": "2025-03-31T23:59:59Z"
  }'

The runner:

1. Scans invoices and credit notes in the period that match the counterparty's eligibility rules
2. Applies the counterparty's commission/share rules to compute the payout amount per line
3. Subtracts platform fees, withholding, or holdback amounts
4. Writes one SettlementLine per source document and totals on the header

Manual settlement

For ad-hoc settlements (one-off bonuses, dispute resolutions), create the header manually and add lines:

Code
curl -X POST /v1/settlements \
  -d '{
    "counterparty_id": "partner_xyz",
    "currency": "EUR",
    "period_start": "2025-03-01T00:00:00Z",
    "period_end": "2025-03-31T23:59:59Z"
  }'

curl -X POST /v1/settlements/{id}/lines \
  -d '{
    "amount": 25000,
    "description": "Referral bonus Q1 2025"
  }'

Finalizing

Code
curl -X POST /v1/settlements/{id}/finalize

Locks the totals and assigns a settlement number. Required before recording a payout.

Recording a payout

Code
curl -X POST /v1/settlements/{id}/record-payout \
  -d '{
    "payout_reference": "TRF-2025-04-002",
    "payout_method": "bank_transfer",
    "paid_at": "2025-04-05T10:00:00Z"
  }'

Emits settlement.payout_recorded. The settlement transitions to payout_recorded; no further changes are allowed.

Withholding and adjustments

Counterparties can carry withholding rules (e.g., reserve 10% for a chargeback buffer) and per-period adjustments (clawbacks, manual corrections). These appear as their own SettlementLine rows with negative amounts and explicit line_type: adjustment.

Reporting

Code
GET /v1/settlements/{id}/pdf       # Counterparty-facing statement
GET /v1/settlements/{id}/csv       # Detailed line-level export

The PDF renders the per-line breakdown and the total payout. The CSV is suitable for the counterparty's own reconciliation against their internal ledger.

Next steps

• Invoices - the source documents settlements aggregate
• Credit Notes - reductions that flow into settlements
• API Reference - Settlements