Marketplace Commission Motor
At a glance
Marketplace Commission Motor is the financial engine that makes every marketplace transaction split correctly between seller and platform — Stripe Connect Express onboarding, atomic stock decrement, transparent 5% commission breakdowns at checkout, proportional reversal on refunds, and idempotent monthly payout and accounting jobs that close the books without manual reconciliation.
How it works
The Commission Motor is the back-end that the Seller Dashboard (F11.06) and the buyer-facing storefront both call into. Sellers are onboarded via Stripe Connect Express — the platform creates the connected account, hosts the KYC flow, and stores the account ID; payouts route directly to the seller's bank without funds touching a platform-held balance. Listings are stored as Commission Listings with full i18n support (title, description, attribute labels in 43+ languages), per-variant stock, category taxonomy aligned with Equipment Catalog (F11.01), and pricing in the seller's chosen currency with FX-converted display prices for the buyer.
At checkout, the Transparent Commission Breakdown shows the buyer the item price, shipping, taxes, and a clearly labeled 5% platform commission line — building trust and pre-empting marketplace complaints. The Atomic Stock Decrement uses a database-level conditional update (decrement only if stock >= quantity) to prevent oversell under race conditions when two buyers hit checkout simultaneously; if the decrement fails, the order is rejected with a 'sold out' message and the payment is never captured. On successful payment, Stripe captures the full amount, transfers seller-net to the connected account, and retains the platform fee in the platform balance.
Refunds invoke Proportional Commission Reversal: if a buyer is refunded 60% of a EUR 100 order, the platform refunds 60% of the original commission as well, keeping seller margins consistent. The Monthly Seller Payout Job runs idempotently on the first of each month, computing each seller's net earnings, generating a settlement statement PDF, and triggering payouts; idempotency keys ensure a re-run never double-pays. The Commission Accounting Job produces a monthly financial report (gross merchandise volume, commission earned, refund liability, FX exposure) for platform finance.
Admin endpoints expose commission reports per seller / period and allow manual refund adjustments for dispute resolution.
Key capabilities
- Stripe Connect Express seller account onboarding with hosted KYC
- Commission listings with i18n, stock, categories, and multi-currency pricing
- 5% platform commission with transparent buyer-facing breakdown
- Atomic stock decrement with race-condition protection on checkout
- Proportional commission reversal on partial and full refunds
- Idempotent monthly seller payout job with PDF settlement statements
- Monthly commission accounting job and admin commission reports
In practice
A buyer in Belgium checks out a EUR 240 set of competition boules from a Spanish seller. The checkout shows: boules EUR 240, shipping EUR 12, VAT EUR 50.40, platform commission EUR 12 — total EUR 314.40. Stock decrements atomically; payment captures; Stripe transfers EUR 240.40 to the Spanish seller's connected account net of commission and Stripe fees.
Two weeks later the buyer requests a partial refund for one defective boule (EUR 60). The motor refunds EUR 60 to the buyer, claws back EUR 3 of commission proportionally, and the seller's next monthly settlement reflects both adjustments without any manual ledger work.
Features in this subsystem
10| ID | Status | Features |
|---|---|---|
| F11.07.01 | Shipped | Stripe Connect Express seller account onboarding — PL-T032 ✅ PL-T032 · ✅ D-COMMERCE 0fa09b8b.m-3 |
| F11.07.02 | Shipped | Commission listing with i18n, stock tracking, categories — PL-T032 ✅ PL-T032 · ✅ D-COMMERCE 0fa09b8b.m-3 |
| F11.07.03 | Shipped | 5% platform commission on marketplace transactions — PL-T032 ✅ PL-T032 · ⊘ ägarbeslut 2026-07-09: ingen provision (D-COMMERCE 0fa09b8b.m-3, BR38.08) |
| F11.07.04 | Shipped | Transparent commission breakdown display — PL-T032 ✅ PL-T032 · ⊘ ägarbeslut 2026-07-09: ingen provision (D-COMMERCE 0fa09b8b.m-3, BR38.08) |
| F11.07.05 | Shipped | Atomic stock decrement with race-condition protection — PL-T032 ✅ PL-T032 |
| F11.07.06 | Shipped | Proportional commission reversal on refunds — PL-T032 ✅ PL-T032 · ⊘ ägarbeslut 2026-07-09: ingen provision (D-COMMERCE 0fa09b8b.m-3, BR38.08) |
| F11.07.07 | Shipped | Monthly seller payout job (idempotent) — PL-T032 ✅ PL-T032 · ⊘ D-COMMERCE 0fa09b8b.m-6 t-1: payouts är Stripe-hanterade per connected account — inget PL-jobb; sys/commerce LÄSER BILL m-10:s payout_reconciliation + payout.failed för säljartenanter (sysCommerceGetPayouts, BR38.28) |
| F11.07.08 | Shipped | Commission accounting job (monthly financial report) — PL-T032 ✅ PL-T032 · ✅ D-COMMERCE 0fa09b8b.m-6 t-1 som VOLYMRAPPORT (ingen provision): jobbet marketplace_volume_report (0 5 1 * *) materialiserar månaden per (tenant, valuta) med samma mätfunktion som sysCommerceGetVolume/sysCommerceExportVolume; aldrig summerad över valutor (BR38.26) |
| F11.07.09 | Shipped | Admin commission report and manual refund endpoints — PL-T032 ✅ PL-T032 · ✅ D-COMMERCE 0fa09b8b.m-6 t-1 (API sys/commerce: sysCommerceGetSettlement/sysCommercePutSettlement — avgiften 0 som policy-egenskap, enda skrivbara talet paketförslagstaket; manuell återbetalning under tvåpersonsregel sysCommercePreviewRefund → sysCommerceConfirmRefundOperation genom executeRefundSeam, constrainten approvers_differ; sysCommerceGetOrder opak; sysCommerceListJobs — specs/api/endpoints/sys-commerce.md, BR38.25—BR38.29) · ✅ t-2 (sys-ytan /commerce: sex sektioner i mockupens ordning — inledning, settlement med fyra läsfält + taket, volymrapport per valuta med FX-raden »—« och CSV, tvåpersonsåterbetalningen med kön *Väntar på andra operatören*, payout-monitorering, jobbtabellen med *Kör nu* genom POST /v1/sys/jobs/run-now; nav-posten sys-nav-commerce 🛒 bara med sys.commerce.read — specs/sys/views/commerce.md, runbook docs/engineering/runbooks/sys-views/commerce.md, L4 tools/gate/dcommerce-m6-e2e.mjs) |
| F11.07.10 | Shipped | Ärlig m-6-gräns för sys/commerce (inget fabricerat) — ingen provision och ingen avgiftsparameter (ägarbeslut 2026-07-09), ingen kurskälla (cross_currency_total: null, ägare BILL), ingen payout-motor och ingen registerrad för payout.failed (ägare BILL/F1-11), inga bulk quotes/leads/prognos (beslut 7, 0fa09b8b.m-1). Övriga tenantpengar står kvar bakom D-SYS m-10:s 403 tenant_funds_not_operable. Ytan sys/commerce (t-2): inga mockup-tal eller främmande jobb (B-6), ingen omräknad summa över valutor (B-2), ingen »månatlig utbetalningskörning« (B-3), payout-monitoreringen bara för säljartenanter (B-4), inget omförsöks-/eskaleringsspråk på failed-kortet (B-7), ordernumret som <TENANTKOD>-<nummer> (B-8); sys beslutar aldrig en säljares retur ✅ D-COMMERCE 0fa09b8b.m-6 t-1 · ✅ t-2 |