Auction Overview

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

warning

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.