---
title: "Commissions & Settlements"
description: "Settlements ledger, referral commission, hold/release, dry-run payouts — dual-rail with refcodes"
locale: "en"
---
# Commissions & Settlements

`settlement.ts` calculates platform commission, optional **referral commission**, and merchant splits. This is the **vendor-funded** rail. Platform-funded **token** rewards live on [refcodes](/docs/features/refcodes.md).

  Same `orderReference` should appear on `settlements`, `erp_sales_assists`, and `referral_rewards` for cross-audit. See [Affiliate enablement](/docs/features/affiliate-enablement.md).

### For founders

## Operator cockpit — `/admin/store/commissions`

| Action | What it does |
|--------|----------------|
| Status filters | Pending / held / completed |
| **Dry-run due payouts** | Counts due rows + net total — no money moved |
| **Process due payouts** | Runs `processDueSettlements` for `scheduledFor <= now` and `status = pending` |
| **Hold** | Blocks a pending settlement from payout (`status = held`) |
| **Release** | Returns a held settlement to pending |
| Referral rates table | Effective % per product with resolver source |

Vendor view: `/vendor/earnings` — pending + history from the same `settlements` collection. Simulated payouts show a **Simulated** badge until on-chain mode is production-verified.

### For developers

## Unified ledger flow

Paid store orders call `VendorSettlementService.processSettlements` → `recordSettlementsForPaidOrder` → `createSettlement` per vendor slice into canonical `settlements`.

Stock commit runs **alongside** (not inside) settlement: handlers call `commitSaleForOrder` then settlements.

| Collection | Role |
|------------|------|
| `settlements` | Commission/payout ledger — admin Commissions, vendor Earnings |
| `payout_batches` | Batch runs from Process due payouts |
| `erp_sales_assists` | Referral-attributed sale rows when `referralCode` is on the order |
| `vendor_settlements` | Legacy log (not written on new paid orders) |

```mermaid
sequenceDiagram
  participant PC as PaymentConductor_handler
  participant SALE as commitSaleForOrder
  participant VS as VendorSettlementService
  participant SP as settlement_pipeline
  participant ST as settlement_ts
  participant DB as PostgreSQL

  PC->>SALE: paid isNew
  SALE->>DB: stock_movements sale
  PC->>VS: processSettlements
  VS->>SP: recordSettlementsForPaidOrder
  SP->>ST: createSettlement
  ST->>DB: settlements
```

### Admin actions (verified)

| Action | Path |
|--------|------|
| `processDueSettlementsAction` | `app/_actions/admin-store-erp.ts` |
| `previewDueSettlementsAction` | dry-run preview |
| `holdSettlementAction` / `releaseHeldSettlementAction` | wraps `holdSettlement` / `releaseHeldSettlement` |
| Cron | ProcessConductor `settlement-payout` → `/api/cron/settlement-payout` |

## Referral commission hierarchy

Shared resolver `features/store/lib/referral-commission.ts`:

| Priority | Source |
|----------|--------|
| 1 | Product `referralCommission` |
| 2 | Merchant `commissionStructure.referralCommission` |
| 3 | Platform default (5%) |
| 4 | Env `REFERRAL_REWARD_PERCENT` |

Optional clamp: `REFERRAL_COMMISSION_MAX_PERCENT` (default `50`).

## Payout modes

| `SETTLEMENT_PAYOUT_MODE` | Behavior |
|--------------------------|----------|
| `simulated` (default) | Completes with `metadata.simulated` / `sim_` id |
| `onchain` | ERC20 via treasury (`SETTLEMENT_PAYOUT_PRIVATE_KEY`, token address, RPC) |

## Database

Migration **`007_settlements_schema.sql`** (plus inventory tables in schema / `008_*`). Dev helper: `./scripts/apply-erp-migrations-dev.sh` when present on the clone.

  
- [features/erp/inventory](/docs/features/erp/inventory.md) — Depends-on: stock commit before settlement side-effects on paid order.

  
- [features/affiliate-enablement](/docs/features/affiliate-enablement.md) — Same-workflow: dual-rail overview and verification checklist.

  
- [features/refcodes](/docs/features/refcodes.md) — See-also: platform-funded token rewards sharing commission resolver.

  
- [features/erp/vendor-management](/docs/features/erp/vendor-management.md) — Next-step: vendor earnings and merchant config context.

  
- [features/payment-conductor](/docs/features/payment-conductor.md) — Prerequisite: paid handlers trigger processSettlements.