Settlements

Overview

Marketplace settlement files and API sync, reconciliation, fee schedules, and courier COD remittance. These are separate models. COD cash and marketplace settlement are not the same table.

Code map

Piece	Path
Feature	src/modules/finance/settlement
Schemas	51-settlement.prisma, 52-cod-remittance.prisma, 53-fee-audit.prisma

Entities include Settlement, SettlementGroup, SettlementTransaction, SettlementImportBatch, SettlementReconciliation, SettlementReconciliationMatch, ChannelSettlementConfig, SettlementJournalEntry, CourierRemittance, CourierRemittanceLine, PlatformFeeSchedule, PlatformFeeRule, SettlementFeeAudit, MarketplaceClaim.

Ingress

• Sync type settlement on sync_queue. Interval constant 24 hours. Concurrency 5.
• Manual import: settlement_queue job upload, concurrency 5, parsers for Amazon, Flipkart, and Meesho files.
• Reconciliation cron 0 2 * * *.

The heavy parse is off the request thread. The processor exists, so the import API queues work. Confirm the controller response in OpenAPI before you promise a synchronous result.

Workflow: Settlement import.

Business rules

Unknown: match tolerance, and what “reconciled” means financially. Do not document a tolerance that was not read from the reconciliation service.

Unknown: whether COD remittance is owned by the courier cash flow or also by marketplace settlement. The schemas are separate.

Amazon settlement sync from the finances API is POST /v1/integrations/amazon/channels/:channelId/settlements/sync with @RequirePermissions('SETTLEMENT:CREATE').

Failure scenarios

A batch can record status while individual lines fail. SettlementImportBatchStatus exists. Line-level partial commit rules are unknown.

API surface

Settlement, import, reconciliation, dashboard, fee rules, journal, and COD remittance controllers.