TWIGZ Backend API Documentation

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.

Id<'stores'>

Filter payouts by a specific store

number

Maximum number of records to return (default: 50)

const pendingPayouts = await convex.query(api.admins.payoutOperations.getPendingPayouts, {
  limit: 50
});

[
  {
    "_id": "p123456789",
    "_creationTime": 1700000000000,
    "storeId": "s123456789",
    "storeName": "Pizza Palace",
    "storeOwnerName": "Ahmed",
    "storeOwnerPhone": "+971501234567",
    "requestedAmount": 500.00,
    "processingFee": 5.00,
    "netAmount": 495.00,
    "bankDetails": {
      "IBAN": "AE070331234567890123456",
      "bankName": "Emirates NBD",
      "accountHolderName": "Ahmed Ali"
    },
    "status": "requested",
    "requestDate": 1700000000000,
    "approvedDate": null,
    "requestedBy": "store_owner_123",
    "currentWalletBalance": 1200.00,
    "totalEarnings": 5000.00,
    "totalOrders": 150
  }
]

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.

object

Optional date range filter with startDate and endDate (Unix timestamps in milliseconds)

const stats = await convex.query(api.admins.payoutOperations.getPayoutStatistics, {});

{
  "totalPendingRequests": 5,
  "totalPendingAmount": 2500.00,
  "totalProcessingRequests": 2,
  "totalProcessingAmount": 1000.00,
  "totalCompletedToday": 3,
  "totalCompletedTodayAmount": 1500.00,
  "totalCompletedThisMonth": 45,
  "totalCompletedThisMonthAmount": 22500.00,
  "averageProcessingTime": 12.5,
  "topStoresByPayouts": [
    {
      "storeId": "s123456789",
      "storeName": "Pizza Palace",
      "totalPayouts": 8,
      "totalAmount": 4000.00
    }
  ]
}

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 in requested status. Updates associated wallet transactions to completed.

Id<'payouts'>

required

Payout request ID to approve

string

required

Admin user ID performing the action

string

Optional notes about the approval decision

await convex.mutation(api.admins.payoutOperations.approvePayout, {
  adminUserId: "admin_123",
  payoutId: "p123456789",
  adminNotes: "Approved after verification"
});

Reject Payout

Rejects a payout request and returns the requested amount to the store’s available wallet balance. The payout must be in requested status. Sets payout status to cancelled and wallet transactions to cancelled.

Id<'payouts'>

required

Payout request ID to reject

string

required

Admin user ID performing the action

string

required

Reason for rejecting the payout

string

Optional additional admin notes

await convex.mutation(api.admins.payoutOperations.rejectPayout, {
  adminUserId: "admin_123",
  payoutId: "p123456789",
  rejectionReason: "Bank details do not match trade license",
  adminNotes: "Store owner contacted to update bank info"
});

Mark Payout As Processing

Marks an approved payout as processing when the bank transfer has been initiated. The payout must be in approved status.

Id<'payouts'>

required

Payout request ID

string

required

Admin user ID performing the action

string

required

Method used to process the payout: bank_transfer, manual, or third_party

string

Bank or third-party transaction reference number

string

Optional admin notes

await convex.mutation(api.admins.payoutOperations.markPayoutAsProcessing, {
  adminUserId: "admin_123",
  payoutId: "p123456789",
  processingMethod: "bank_transfer",
  transactionReference: "ENBD-TXN-20240115-001"
});

Complete Payout

Marks a processing payout as completed. Updates wallet statistics including total payouts and last payout date. The payout must be in processing status.

Id<'payouts'>

required

Payout request ID

string

required

Admin user ID performing the action

string

Final transaction reference (overrides existing if provided)

string

Optional admin notes

await convex.mutation(api.admins.payoutOperations.completePayout, {
  adminUserId: "admin_123",
  payoutId: "p123456789",
  transactionReference: "TXN123456789"
});

Mark Payout As Failed

Marks an approved or processing payout as failed. Optionally restores the requested amount to the store’s available wallet balance.

Id<'payouts'>

required

Payout request ID

string

required

Admin user ID performing the action

string

required

Reason for the failure (e.g., invalid IBAN, bank rejection)

string

Optional admin notes

boolean

Whether to restore the payout amount back to the store’s available balance (default: false)

await convex.mutation(api.admins.payoutOperations.markPayoutAsFailed, {
  adminUserId: "admin_123",
  payoutId: "p123456789",
  failureReason: "Bank rejected transfer - invalid IBAN",
  restoreBalance: true,
  adminNotes: "Store owner notified to update bank details"
});

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.

Id<'stores'>

required

Store ID owning the wallet

Id<'storeWallets'>

required

Wallet ID to adjust

string

required

Type of adjustment:

add_balance — Add to available balance (recorded as bonus transaction)
deduct_balance — Deduct from available balance (recorded as penalty transaction)
add_pending — Add to pending balance
deduct_pending — Deduct from pending balance
move_pending_to_available — Transfer amount from pending to available balance

number

required

Adjustment amount (must be positive)

string

required

Reason for the adjustment (recorded in transaction description)

string

required

Admin user ID performing the adjustment

string

Optional additional notes (stored in transaction metadata)

await convex.mutation(api.admins.payoutOperations.adjustWalletBalance, {
  storeId: "s123456789",
  walletId: "w123456789",
  adjustmentType: "add_balance",
  amount: 100.00,
  reason: "Compensation for platform error on order #1234",
  adminUserId: "admin_123",
  adminNotes: "Approved by operations manager"
});

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.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Payout Operations

Overview

Get Pending Payouts

Get Payout Statistics

Approve Payout

Reject Payout

Mark Payout As Processing

Complete Payout

Mark Payout As Failed

Adjust Wallet Balance

​Overview

​Get Pending Payouts

​Get Payout Statistics

​Approve Payout

​Reject Payout

​Mark Payout As Processing

​Complete Payout

​Mark Payout As Failed

​Adjust Wallet Balance

Overview

Get Pending Payouts

Get Payout Statistics

Approve Payout

Reject Payout

Mark Payout As Processing

Complete Payout

Mark Payout As Failed

Adjust Wallet Balance