SudoSOS Back-end API / seller-payouts
Seller Payouts ​
A seller-payout settles sales credit from SudoSOS to an organ. Every SubTransactionRow that crosses the till credits the container-owner's user account (ORGAN users hold this credit). Once a quarter, or whenever the organ asks for a settlement, a treasurer creates a seller-payout that sweeps the accumulated credit back out to the real-world bank account.
Snapshot at creation, not a live link ​
Each SellerPayout covers a [startDate, endDate] window of revenue. At creation time createSellerPayout asks SalesReportService for a report over that window and copies report.totalInclVat onto the entity. From then on the amount is frozen on both the payout and its linked Transfer; the payout does not re-query the report.
That snapshot can drift from reality. If a sub-transaction inside the window is changed or deleted after the payout exists (a refund, an admin correction), the snapshot and a fresh report for the same window no longer agree. Detecting this is what GET /seller-payouts/{id}/report is for: it re-runs the sales report with the payout's stored window and requestedBy, so the treasurer can compare the live total against payout.amount. PATCH /seller-payouts/{id} is the lever for reconciling once drift is found.
Overlapping windows for the same seller are still refused, so the same revenue cannot be paid out twice. The refusal only checks date ranges though, not whether the prior payout still matches its window.
One transfer, no approval step ​
Unlike a PayoutRequest, a seller-payout has no status state machine. It is treasurer-initiated and lands already-final. POST /seller-payouts creates the SellerPayout and a single debit Transfer (from = requestedBy, the seller user; to = null, since the money leaves SudoSOS) in one go. requestedBy on BasePayout is the seller being paid out, despite the name carried over from payout-requests.
Editing and deleting ​
PATCH /seller-payouts/{id} lets the treasurer adjust amount and reference after creation, typically used to reconcile drift surfaced by the /report endpoint. The linked transfer's amountInclVat is updated in lockstep. DELETE /seller-payouts/{id} removes both the payout row and its transfer; this is an admin escape hatch, not a regular user action.
Inspecting the window ​
GET /seller-payouts/{id}/report returns the live sales report for the stored window (see the drift note above). GET /seller-payouts/{id}/report/pdf is the printable version. SellerPayout itself is PdfAble too: GET /seller-payouts/{id}/pdf produces the payout receipt using the snapshotted amount, with the period and the reference printed on it.
Classes ​
| Class | Description |
|---|---|
| SellerPayout | - |
| SellerPayoutController | Controller for the /seller-payouts endpoints in the seller-payouts module. The amount is snapshotted from SalesReportService at creation time, so GET /seller-payouts/<id>/report re-runs the report live for drift detection and PATCH /seller-payouts/<id> is the lever for reconciling once drift is found. |
| SellerPayoutService | - |
Interfaces ​
| Interface | Description |
|---|---|
| CreateSellerPayoutParams | - |
| CreateSellerPayoutRequest | - |
| PaginatedSellerPayoutResponse | - |
| SellerPayoutFilterParameters | - |
| SellerPayoutResponse | - |
| UpdateSellerPayoutRequest | - |
Functions ​
| Function | Description |
|---|---|
| parseSellerPayoutFilters | - |