Overview

Budget management allows store owners to set spending limits for cash and credit purchases. When enabled, the system validates orders against budget limits and can automatically adjust payment types if one budget is exceeded. Budgets are tracked separately and updated as orders are completed.

• Optional Feature: Budgets are disabled by default. Store owners enable them in buylist configuration.
• Separate Tracking: Cash and credit budgets are tracked independently.
• Automatic Adjustment: If one budget is exceeded but the other has sufficient funds, system can automatically switch payment types.
• POS Buys Excluded: Budget validation is skipped for orders created via POS Buy Mode.

Budget Configuration

• Enable Budgets: Set buylistConfig.config.budgetsEnabled = true
• Cash Budget: Set cashBudget to total amount available for cash purchases
• Credit Budget: Set creditBudget to total amount available for credit purchases
• Budget Tracking: System tracks cashBudgetUsed and creditBudgetUsed (initially 0)
• Storage: Budgets stored in UserModel.buylistConfig.config object

Budget Validation Process

1. Order Submission: When customer submits order, system calls validateAndAdjustBudget() function
2. Skip Check: If budgets disabled or POS buy, validation skipped and order proceeds
3. Calculate Remaining:
   • cashRemaining = cashBudget - cashBudgetUsed
   • creditRemaining = creditBudget - creditBudgetUsed
4. Check Both Budgets:
   • If totalCash > cashRemaining AND totalCredit > creditRemaining: Order rejected with error
   • Error message: "Insufficient budget for both cash and credit. Please contact the store to increase budget limits."
   • Response includes cashRemaining and creditRemaining values
5. Automatic Cash to Credit Switch:
   • If totalCash > cashRemaining BUT creditRemaining >= totalCredit:
   • All Cash items converted to Credit items
   • addedCashPrice moved to addedCreditPrice, addedCashPrice set to 0
   • adjustedTotalCash = 0, adjustedTotalCredit = totalCash + totalCredit
   • Warning message: "Budget limit reached for one payment type. Order has been automatically switched to the other payment type."
6. Automatic Credit to Cash Switch:
   • If totalCredit > creditRemaining BUT cashRemaining >= totalCash:
   • All Credit items converted to Cash items
   • addedCreditPrice moved to addedCashPrice, addedCreditPrice set to 0
   • adjustedTotalCredit = 0, adjustedTotalCash = totalCash + totalCredit
   • Warning message shown to customer
7. Success: If budgets sufficient, returns success: true with remaining amounts

Budget Updates

• When Updated: Budgets updated when order is successfully submitted (after validation)
• Update Method: Uses MongoDB $inc operator to increment used amounts
• Update Logic:
  • cashBudgetUsed += finalTotalCash
  • creditBudgetUsed += finalTotalCredit
  • Skipped if budgets disabled or POS buy
• Atomic Operation: Budget update uses MongoDB atomic increment to prevent race conditions
• Order Status: Budgets updated regardless of initial order status (pending_approval, approved, etc.)

Use Cases

• Controlled Spending: Limit total cash spent on buylist purchases per period
• Cash Flow Management: Ensure sufficient cash reserves for other business needs
• Credit Limits: Control amount of store credit issued via buylist orders
• Monthly Budgets: Reset budgets monthly to track spending cycles
• Department Budgets: Separate budgets for different product categories or departments
• Tournament Budgets: Set specific budgets for tournament buying periods

Resetting Budgets

To reset budgets (e.g., at start of new month or period):

• Reset Used Amounts: Set cashBudgetUsed = 0 and creditBudgetUsed = 0
• Adjust Budget Amounts: Update cashBudget and creditBudget to new limits
• Via API: Update via PATCH /api/buylist/store/config endpoint
• Via UI: Update in buylist configuration page

Best Practices

• Regular Monitoring: Check budget usage regularly to track spending patterns
• Realistic Limits: Set budgets based on actual cash flow and purchasing needs
• Buffer Amounts: Include buffer in budgets to account for unexpected high-value orders
• Communication: Inform customers if budgets are enabled and what limits apply
• Quick Adjustments: Have process to quickly increase budgets for urgent purchases
• Track Trends: Use budget usage data to understand seasonal buying patterns