Auction Overview
The auction system provides a comprehensive bidding platform where users can participate in timed auctions with automatic escrow handling, immediate refunds, and flexible purchase options.
Auction Lifecycle
Auction Creation
Sellers can create auctions with optional reserve prices and buy now prices
Auctions can be set for website or social media platforms
Each auction has a specific end date and time
Auctions start in "active" status and accept bids immediately
Active Bidding Period
Users can place bids above the current highest bid plus minimum increment
Each bid includes an escrow fee calculated as a percentage of the bid amount
When a user places a higher bid, the previous highest bidder is automatically refunded
Users can also use the "Buy Now" option to purchase immediately at a fixed price
The system automatically adds auctions to users' watchlists when they place bids
Auction End Process
Auctions end automatically at their scheduled time or when Buy Now is used
If the reserve price is met, the highest bidder wins and an escrow is created
If the reserve price is not met, the auction ends unsold and the highest bidder is refunded
The system processes auction endings through scheduled commands every minute
Escrow Process
When an auction sells, an escrow is automatically created between buyer and seller
The escrow includes the winning bid amount plus escrow fees
Both buyer and seller receive notifications about the escrow creation
The escrow has a time limit for completion, after which it can be cancelled
If the escrow fails, the auction is marked as "escrow_failed" and the seller can re-list either as auction or change it to fixed price (regular sale).
Bidding Rules
Bid Placement
Users must have sufficient balance to cover the bid amount plus escrow fees
Bids must meet the minimum increment above the current highest bid
All monetary amounts are rounded to 2 decimal places for precision
Users cannot bid on their own auctions
Immediate Refunds
When a user is outbid, their funds are immediately refunded to their balance
The refund includes both the bid amount and escrow fees
Refunded bids are marked with an "is_refunded" flag to prevent double refunds
Users receive notifications when they are outbid
Buy Now Functionality
Buy Now is available throughout the auction period, even after bids are placed
When Buy Now is used, all other bidders are automatically refunded
The auction ends immediately and an escrow is created for the buyer
Buy Now price includes escrow fees calculated at the time of purchase
Escrow System
Auction Escrow Creation
Escrows are automatically created when auctions end with a winner
The escrow links to the winning bid record for proper tracking
Both buyer and seller receive email and in-app notifications
The escrow has a configurable expiration time
Escrow Completion
When the buyer confirms account information, the escrow is completed
The seller receives the original bid amount (excluding escrow fees)
The escrow fees remain in the system as transaction fees
Both parties receive completion notifications
Escrow Failure Handling
If escrows expire or are cancelled, the auction is marked as "escrow_failed"
The buyer is fully refunded including escrow fees
All bid records are deleted to provide a clean slate
The seller can choose to re-list the auction or convert it to fixed price
Re-listing System
Seller Options After Escrow Failure
Sellers can re-list failed auctions with a new end date
Sellers can convert failed auctions to fixed price listings
When re-listing, all previous bids are cleared for a fresh start
The system regenerates URLs when converting between auction and fixed price
Notification System
Bid Notifications
Sellers receive notifications when new bids are placed on their auctions
Users receive notifications when they are outbid
Auction watchers receive notifications about new bids and auction endings
All notifications include relevant amounts and action links
Escrow Notifications
Both buyers and sellers receive escrow creation notifications
Notifications include escrow details and expiration information
Completion and cancellation notifications are sent to both parties
Email notifications are sent based on admin settings
Security & Validation
Race Condition Prevention
The system uses row-level locking to prevent multiple users from purchasing the same auction
All auction modifications are wrapped in database transactions
The system re-validates auction status after locking to ensure consistency
Balance Protection
Users cannot bid or buy if they have insufficient balance
The system calculates exact amounts needed including escrow fees
All balance operations are atomic and include proper validation
Negative balances are prevented through comprehensive checks
Access Control
Users can only bid on active auctions
Users cannot bid on their own auctions
Ongoing escrows prevent new bids or purchases
Only auction owners can re-list failed auctions
Automated Processes
The auction system relies on automated processes, including closing expired auctions, canceling expired escrows, sending auction ending notifications, processing expired auctions, triggering automatic refunds for failed escrows, and maintaining bid records. To ensure these processes function correctly, it is essential to configure cron jobs within your cPanel or hosting provider.
Scheduled Commands
The system runs commands every minute to close expired auctions
Expired escrows are automatically cancelled every 5 minutes
Auction ending notifications are sent 24 hours before expiration
All automated processes include proper error handling and logging
Data Cleanup
Expired auctions are automatically processed and closed
Failed escrows trigger automatic refunds and status updates
Old bid records are maintained for audit purposes
The system logs all automated actions for monitoring
User Experience Features
Real-time Updates
Countdown timers show time remaining or "Auction Ended"
Bid history displays all bids with winner indicators
Status displays show current auction state clearly
Loading states provide feedback during actions
Interactive Elements
Bid confirmation modals show amounts and fees before placing bids
Buy Now modals display purchase details and refund calculations
Watch/unwatch buttons allow users to track auctions
Responsive design works on all devices and themes
This auction system provides a complete, secure, and user-friendly platform for online auctions with comprehensive escrow handling and automated processes.
Last updated