Overview
Payout Operations API provides administrative functions for processing store payout requests, managing payout workflows, reviewing payout statistics, and handling wallet balance adjustments. Location:convex/admins/payoutOperations.ts
Get Pending Payouts
Retrieves pending payout requests for admin review. Can filter by store or return all pending payouts. Returns enriched data including store details, wallet balances, and bank information.Get Payout Statistics
Returns payout statistics for the admin dashboard, including pending/processing counts, completed totals for today and this month, average processing time, and top stores by payout volume.averageProcessingTime is measured in hours. topStoresByPayouts returns up to 10 stores sorted by total payout amount this month.Approve Payout
Approves a payout request. The payout must be inrequested status. Updates associated wallet transactions to completed.
Reject Payout
Rejects a payout request and returns the requested amount to the store’s available wallet balance. The payout must be inrequested status. Sets payout status to cancelled and wallet transactions to cancelled.
Mark Payout As Processing
Marks an approved payout as processing when the bank transfer has been initiated. The payout must be inapproved status.
Complete Payout
Marks a processing payout as completed. Updates wallet statistics including total payouts and last payout date. The payout must be inprocessing status.
Mark Payout As Failed
Marks an approved or processing payout as failed. Optionally restores the requested amount to the store’s available wallet balance.When
restoreBalance is true, the requested amount is returned to the store’s available balance and associated wallet transactions are marked as failed. Use this when the bank transfer was rejected and the funds should be made available again.Adjust Wallet Balance
Manually adjusts a store’s wallet balance. Supports adding/deducting available balance, adding/deducting pending balance, or moving funds from pending to available. Records a wallet transaction for audit purposes.Type of adjustment:
add_balance— Add to available balance (recorded asbonustransaction)deduct_balance— Deduct from available balance (recorded aspenaltytransaction)add_pending— Add to pending balancededuct_pending— Deduct from pending balancemove_pending_to_available— Transfer amount from pending to available balance
All wallet adjustments are audited via wallet transactions. The
move_pending_to_available type does not create a transaction record as it is a net-zero operation. Deductions will fail if the wallet has insufficient balance.