Settlement

Quick summary

Creating a settlement calculates and records amounts; it does not prove money was paid out. Distinguish pending accrual from a confirmed transfer.

Review eligibility, fee calculation, claim batches, and recovery limitations before running the operation; do not treat multiple D1 batches as one transaction.

Settlement is a manual accrual run — POST /api/v1/settlements (seller). From be-cloudflare/src/settle_impl.rs:

Preconditions

• Seller must be approved: verification.status='APPROVED' is required — unapproved sellers cannot settle.
• Targets are the seller's orders with status IN ('paid','partially_refunded')and settlement_id IS NULL, net of refunded_krw.

The run (multi-batch; recovery is not yet guaranteed)

D1 transaction boundary

Each individual D1 batch is atomic, but multiple batches in one settlement run are not one transaction. A process interruption can leave orders claimed before the settlement record exists. Review the Financial Integrity gap analysis before operational use.

1. Sequence: UPDATE counters SET n=n+1 WHERE name='settlement' RETURNING n → settlement number ST-YYYY-NNNN.
2. Claim: each target order is claimed via conditional UPDATE orders SET settlement_id=? WHERE id=? AND settlement_id IS NULL with affected=1 verification — a concurrently-claimed order is skipped, a condition intended to avoid double claims. If the settlement insert later fails, the code attempts to release the claimed orders (settlement_id=NULL).
3. Record: INSERT INTO settlements (…, status='pending', …) with gross_krw, pg_fee_krw, platform_fee_krw, net_krw computed from seller_settings rates (pg_fee_rate, platform_fee_rate), plus order_ids_json.
4. Ledger + audit + outbox in the same batch: transaction_ledgersettlement entry, audit_events settle entry (integrity-hash chained), outbox settlement.settle event.

Response: {ok:true, id, settlement_no, status:"pending", gross_krw, net_krw, orders}.

Status model

• The settlement is born pending — payout is a separate stage; creation-time status is never paid.
• There is no seller plan/billing collection path — platform_fee_krw accrues at settlement but nothing collects it yet (limitations §3.4).

Reading

GET /api/v1/settlements (seller-own / admin). Seller console page: fe/pages/settlements/.

Related

• Orders feed settlement; refunds reduce amount_krw via refunded_krw before accrual.
• Fee rates live in seller_settings (GET/PATCH /settings).
• Integrity: ledger and audit entries have verification endpoints, but full correctness and external settlement reconciliation remain unverified (GET /ledger/verify, GET /audit/verify, admin).