Marketplace with Settlements
The two-sided marketplace pattern: buyers pay the platform, the platform retains a commission (and any platform fees, taxes, or processing costs), and the remaining amount settles to the seller on a recurring cadence - typically weekly or monthly. The hard part is not collecting from buyers; it's getting the seller payouts right at scale, with full audit trails, and surviving the partner disputes that come every quarter.
Real-world examples. Etsy (sellers paid weekly via direct deposit, fees deducted), Shopify Payments (per-transaction fees + monthly subscription, settles daily), Uber and DoorDash (driver/courier paid weekly with per-trip breakdowns), Airbnb (host paid 24h after check-in), Substack (creator paid monthly with platform cut), Patreon, OnlyFans. Common shape: per-transaction commission rate (5-30%), separate platform fees, weekly or monthly settlement cycle, partner-facing PDF statements, dispute reconciliation tooling.
The shape of the problem
Two-sided money flow means twice the operational surface:
- Buyer-side billing is "easy" - it's a normal invoice or one-shot charge. The hard parts are seller-side.
- Seller payout reconciliation. For each settlement period, you must: aggregate every transaction the seller was party to, apply the per-transaction commission rule, subtract any seller-specific deductions (refunds, chargebacks, platform fees), and produce both the payout amount and the line-by-line statement that justifies it.
- Disputes. Sellers will dispute totals - sometimes monthly. The reconciliation tooling has to let support drill from the payout total down to the individual transaction, including any FX conversion that happened in between.
- Withholding and holdbacks. Many marketplaces hold a percentage of payouts as a chargeback reserve. Some hold the whole payout for a period (Airbnb's 24-hour host hold). Some apply per-jurisdiction tax withholding.
- Multi-tier commission rules. "10% commission, 7% if seller did >$10k last month, 5% if they're a verified Pro seller" - tier-based commission rules layered on top of a base rate.
- Seller-facing transparency. Sellers expect a real-time dashboard showing pending payouts, completed settlements, and the per-transaction breakdown. Anything less generates support tickets.
Kontorion blueprint
| Concern | Kontorion primitive |
|---|---|
| Buyer-side charging | Standard invoices + payments |
| Per-transaction commission record | Settlement.lines with commission_rate per line |
| Seller payout aggregation | Settlement per (counterparty, period) |
| Tier-based commission rules | Counterparty configuration with conditional rates |
| Withholding / chargeback reserve | Settlement withholding rules + adjustment lines |
| Per-seller dashboard | GET /settlements?counterparty_id={seller} |
| Dispute drill-down | Settlement.lines references the source invoice/transaction IDs |
| Partner-facing statement | GET /settlements/{id}/pdf |
Build it
1. Configure the seller as a counterparty
Code
This seller pays a flat 10% commission and 5% is withheld for chargeback reserve, released after 90 days.
2. Process a buyer transaction
A regular invoice generation, with the seller's counterparty ID stamped on the invoice metadata so the settlement runner finds it later:
Code
3. Schedule the weekly payout run
Code
Every Monday at 4am ET, the runner aggregates every paid transaction from the prior week, generates one settlement per seller, and emits settlement.generated for each.
4. Inspect a generated settlement
Code
Code
5. Finalize and record the payout
After your finance team reviews, finalize and record the bank transfer:
Code
The seller gets a settlement.payout_recorded webhook (or email, configured per counterparty) with a link to the PDF statement.
Variations
- Tiered commission rates. Replace the flat
commission_rulesentry with multiple conditional entries:[{condition: "monthly_volume > 1000000", rate: 0.05}, {condition: "verified_pro = true", rate: 0.07}, {rate: 0.10}]. The runner picks the first match. - Per-category commissions. Add a
metadata.categoryfield on each transaction line. Counterparty rules:{ category: "electronics", rate: 0.08 }, { category: "handmade", rate: 0.12 }. - Multi-currency settlements. When buyers pay in different currencies than the seller's payout currency, the settlement runner converts each line via the org's FX policy and pins the rate ID per line for replay.
- Refund and chargeback handling. Buyer-side credit notes automatically generate a corresponding negative
transactionline on the next settlement, clawing back the commission you already paid out. - Holdback release. The 90-day chargeback reserve releases automatically as a positive
adjustmentline on the settlement that lands 90 days later. - Tax withholding for international sellers. Add a
withholding_ruleof typetaxkeyed off the seller's country - e.g. 10% withholding for non-US sellers under W-8BEN regime, included as a separate adjustment line on every settlement.
What you don't have to build
- Per-seller transaction aggregation (settlement runner does it on the cron)
- Commission math with tier conditions (counterparty rules engine)
- Chargeback reserve bookkeeping with timed release (withholding rules)
- FX conversion for cross-currency settlements (FX policy applies)
- Refund clawback on already-paid-out commissions (credit notes flow through)
- Partner-facing PDF statement (
/settlements/{id}/pdfrenders it) - Real-time pending payout dashboard (filter
/settlements?status=draft) - Audit trail for every dispute (each settlement line references its source invoice ID)
Next steps
- Credit Notes - refund handling
- Exchange Rates - FX for multi-currency marketplaces
- Custom Fields - structured seller metadata for commission rule conditions