Scanning documentation library
Scanning documentation library
Scanning documentation library
settlement.ts calculates platform commission, optional referral commission (when referralCode is present on the order), and custom splits from merchant configuration.
Paid store orders (WayForPay webhook or credit rail) call VendorSettlementService.processSettlements, which delegates to recordSettlementsForPaidOrder in settlement-pipeline.ts. That invokes createSettlement per vendor slice and writes the canonical settlements table.
| Collection | Role |
|---|---|
settlements | Commission/payout ledger — admin Commissions tab, vendor Earnings, processDueSettlements |
vendor_settlements | Legacy processing log (no longer written on new paid orders) |
payout_batches | Batch runs from admin Process due payouts |
erp_sales_assists | Referral-attributed sale rows when referralCode is on the order |
Stock movements from deductStockForOrder include referralCode and assisted when attribution is present.
Each payout creates a row in the settlements collection with vendorId, orderId, commission, netPayout, status, and scheduledFor.
/admin/store/commissions lists settlements and exposes Process due payouts (processDueSettlements) for settlements where scheduledFor <= now and status = pending.
resolveReferralCommissionPercent in features/store/lib/referral-commission.ts is shared by ERP settlement and refcodes token rewards:
| Priority | Source | Field |
|---|---|---|
| 1 | Product override | product.referralCommission or product.commissionStructure.referralCommission |
| 2 | Merchant config | merchantConfig.commissionStructure.referralCommission |
| 3 | Platform constant | DEFAULT_COMMISSION_STRUCTURE.referralCommission (5%) |
| 4 | Clone env fallback | REFERRAL_REWARD_PERCENT |
Mixed-rate carts use a subtotal-weighted effective percent. Vendors may set per-product overrides in the product editor; merchant-level rates are admin-managed (read-only on /vendor/settings). Admin Commissions tab lists effective rates per product with source tier.
Optional env: REFERRAL_COMMISSION_MAX_PERCENT (default 50) clamps all resolved values.
RING, DAAR, and DAARION payouts route through merchant walletId.
SETTLEMENT_PAYOUT_MODE | Behavior |
|---|---|
simulated (default) | Completes with metadata.simulated: true and sim_ transaction id — admin Commissions and vendor Earnings show a Simulated badge |
onchain | ERC20 transfer via treasury wallet (SETTLEMENT_PAYOUT_PRIVATE_KEY, SETTLEMENT_PAYOUT_TOKEN_ADDRESS, POLYGON_RPC_URL) |
Use simulated until WayForPay/RING payout rails are production-verified.
Migration 007_settlements_schema.sql creates settlements, payout_batches, merchant_configs, vendor_settlements, stock_movements, erp_sales_assists.
# Dev (005 refcodes + 007 ERP)
./scripts/apply-erp-migrations-dev.sh
# Prod (k8s jump host)
K8S_NAMESPACE=ring-platform-org POSTGRES_DB=ring_platform POSTGRES_USER=ring_user \
./scripts/apply-erp-migrations-prod.shApply 005_refcodes_schema.sql first on clones that lack refcodes tables.
settlement.ts calculates platform commission, optional referral commission (when referralCode is present on the order), and custom splits from merchant configuration.
Paid store orders (WayForPay webhook or credit rail) call VendorSettlementService.processSettlements, which delegates to recordSettlementsForPaidOrder in settlement-pipeline.ts. That invokes createSettlement per vendor slice and writes the canonical settlements table.
| Collection | Role |
|---|---|
settlements | Commission/payout ledger — admin Commissions tab, vendor Earnings, processDueSettlements |
vendor_settlements | Legacy processing log (no longer written on new paid orders) |
payout_batches | Batch runs from admin Process due payouts |
erp_sales_assists | Referral-attributed sale rows when referralCode is on the order |
Stock movements from deductStockForOrder include referralCode and assisted when attribution is present.
Each payout creates a row in the settlements collection with vendorId, orderId, commission, netPayout, status, and scheduledFor.
/admin/store/commissions lists settlements and exposes Process due payouts (processDueSettlements) for settlements where scheduledFor <= now and status = pending.
resolveReferralCommissionPercent in features/store/lib/referral-commission.ts is shared by ERP settlement and refcodes token rewards:
| Priority | Source | Field |
|---|---|---|
| 1 | Product override | product.referralCommission or product.commissionStructure.referralCommission |
| 2 | Merchant config | merchantConfig.commissionStructure.referralCommission |
| 3 | Platform constant | DEFAULT_COMMISSION_STRUCTURE.referralCommission (5%) |
| 4 | Clone env fallback | REFERRAL_REWARD_PERCENT |
Mixed-rate carts use a subtotal-weighted effective percent. Vendors may set per-product overrides in the product editor; merchant-level rates are admin-managed (read-only on /vendor/settings). Admin Commissions tab lists effective rates per product with source tier.
Optional env: REFERRAL_COMMISSION_MAX_PERCENT (default 50) clamps all resolved values.
RING, DAAR, and DAARION payouts route through merchant walletId.
SETTLEMENT_PAYOUT_MODE | Behavior |
|---|---|
simulated (default) | Completes with metadata.simulated: true and sim_ transaction id — admin Commissions and vendor Earnings show a Simulated badge |
onchain | ERC20 transfer via treasury wallet (SETTLEMENT_PAYOUT_PRIVATE_KEY, SETTLEMENT_PAYOUT_TOKEN_ADDRESS, POLYGON_RPC_URL) |
Use simulated until WayForPay/RING payout rails are production-verified.
Migration 007_settlements_schema.sql creates settlements, payout_batches, merchant_configs, vendor_settlements, stock_movements, erp_sales_assists.
# Dev (005 refcodes + 007 ERP)
./scripts/apply-erp-migrations-dev.sh
# Prod (k8s jump host)
K8S_NAMESPACE=ring-platform-org POSTGRES_DB=ring_platform POSTGRES_USER=ring_user \
./scripts/apply-erp-migrations-prod.shApply 005_refcodes_schema.sql first on clones that lack refcodes tables.
settlement.ts calculates platform commission, optional referral commission (when referralCode is present on the order), and custom splits from merchant configuration.
Paid store orders (WayForPay webhook or credit rail) call VendorSettlementService.processSettlements, which delegates to recordSettlementsForPaidOrder in settlement-pipeline.ts. That invokes createSettlement per vendor slice and writes the canonical settlements table.
| Collection | Role |
|---|---|
settlements | Commission/payout ledger — admin Commissions tab, vendor Earnings, processDueSettlements |
vendor_settlements | Legacy processing log (no longer written on new paid orders) |
payout_batches | Batch runs from admin Process due payouts |
erp_sales_assists | Referral-attributed sale rows when referralCode is on the order |
Stock movements from deductStockForOrder include referralCode and assisted when attribution is present.
Each payout creates a row in the settlements collection with vendorId, orderId, commission, netPayout, status, and scheduledFor.
/admin/store/commissions lists settlements and exposes Process due payouts (processDueSettlements) for settlements where scheduledFor <= now and status = pending.
resolveReferralCommissionPercent in features/store/lib/referral-commission.ts is shared by ERP settlement and refcodes token rewards:
| Priority | Source | Field |
|---|---|---|
| 1 | Product override | product.referralCommission or product.commissionStructure.referralCommission |
| 2 | Merchant config | merchantConfig.commissionStructure.referralCommission |
| 3 | Platform constant | DEFAULT_COMMISSION_STRUCTURE.referralCommission (5%) |
| 4 | Clone env fallback | REFERRAL_REWARD_PERCENT |
Mixed-rate carts use a subtotal-weighted effective percent. Vendors may set per-product overrides in the product editor; merchant-level rates are admin-managed (read-only on /vendor/settings). Admin Commissions tab lists effective rates per product with source tier.
Optional env: REFERRAL_COMMISSION_MAX_PERCENT (default 50) clamps all resolved values.
RING, DAAR, and DAARION payouts route through merchant walletId.
SETTLEMENT_PAYOUT_MODE | Behavior |
|---|---|
simulated (default) | Completes with metadata.simulated: true and sim_ transaction id — admin Commissions and vendor Earnings show a Simulated badge |
onchain | ERC20 transfer via treasury wallet (SETTLEMENT_PAYOUT_PRIVATE_KEY, SETTLEMENT_PAYOUT_TOKEN_ADDRESS, POLYGON_RPC_URL) |
Use simulated until WayForPay/RING payout rails are production-verified.
Migration 007_settlements_schema.sql creates settlements, payout_batches, merchant_configs, vendor_settlements, stock_movements, erp_sales_assists.
# Dev (005 refcodes + 007 ERP)
./scripts/apply-erp-migrations-dev.sh
# Prod (k8s jump host)
K8S_NAMESPACE=ring-platform-org POSTGRES_DB=ring_platform POSTGRES_USER=ring_user \
./scripts/apply-erp-migrations-prod.shApply 005_refcodes_schema.sql first on clones that lack refcodes tables.