Auction for OpenCart Extension

Purpletree Auction for OpenCart 4.x

Purpletree Auction is an OpenCart extension that allows store administrators to convert regular products into auction products. The extension provides functionality for creating and managing auctions, configuring auction pricing and bidding rules, managing scheduled auctions, processing winners, and monitoring auction activity.

Complete Auction Management

Purpletree Auction provides the following auction functionality:

• Create and manage auction products
• Configure starting price
• Configure minimum bid increment
• Configure tiered bid increments
• Configure reserve price
• Configure Buy It Now price
• Configure auction start and end time
• Live auction countdown
• Manual bidding
• Proxy/Automatic bidding
• Bid history
• Customer bidding history
• Won Auctions
• Automatic winner selection
• Scheduled auction activation
• Admin auction and bid monitoring
• Customer and admin email notifications
• Cron-based auction processing

Auction Pricing and Bidding

Starting Price

Starting Price defines the minimum amount required for the first valid bid.

Minimum Bid Increment

Minimum Bid Increment defines the minimum amount by which a new bid must exceed the current bid.

Tiered Bid Increments

The administrator can configure different increments based on the current auction price. If no configured tier matches the current price, the auction's default minimum increment is used.

Reserve Price

Reserve Price defines the minimum value required for an auction to produce a winner. The reserve price remains hidden from customers when configured as a hidden reserve.

A global reserve can also be configured for auctions where the individual auction reserve is set to zero.

Buy It Now Price

Buy It Now allows a logged-in customer to immediately purchase the auction product at a fixed price.

Set the Buy It Now price to 0 to disable Buy It Now for that auction.

Buy It Now Processing

When Buy It Now succeeds:

• Auction is locked for processing
• Customer becomes the winner
• Final price is stored
• Product and selected options are added to cart
• Buy It Now price is applied
• Auction status changes to Ended

Auction Scheduling

Start Time

Start Time defines when the auction should become active.

• Before the start time: Pending
• After the start time: Active

The transition is processed by the auction cron.

End Time

End Time defines when the auction should finish. After the configured end time, the auction status changes to Ended. The cron process then performs winner selection based on valid bids and reserve conditions.

Storefront Auction Features

Auction Collection

Active and scheduled auction products can be displayed on the storefront and dedicated Live Auctions collection.

Auction product cards display:

• Product image
• Product information
• Auction price information
• Countdown
• Auction action buttons

Auction Countdown

The countdown displays:

• Days
• Hours
• Minutes
• Seconds

The countdown updates approximately every 1 second. On normal home-page product cards, auction information can appear on hover. The dedicated auction collection displays the auction information directly.

Live Bid Updates

While the auction product page remains open, the following information is refreshed approximately every 5 seconds:

• Current bid
• Minimum next bid
• Reserve status
• Bid history

The implementation uses polling and does not require WebSocket connections.

Manual Bidding

Customers must be logged in before placing a bid.

The entered bid must satisfy the applicable minimum:

• Starting Price for the first bid
• Current Bid + Applicable Increment for subsequent bids

The bid-processing system uses database transactions to help prevent conflicting concurrent bid updates.

Proxy and Automatic Bidding

Proxy Bidding allows a customer to specify a private maximum bid.

The system can automatically increase the customer's bid according to the configured increment when another customer places a higher bid, without exceeding the customer's private maximum.

If another customer exceeds the customer's maximum bid, the customer becomes Outbid.

Automatic Bidding Controls

The administrator can control:

• Whether automatic bidding is enabled
• Whether automatic increments use the normal increment
• Whether customers can modify their proxy maximum multiple times

Bid History

Customers can expand Bid History on the auction product page.

Depending on the administrator's visibility settings, bid history can display:

• Bid amount
• Bidder name
• Bid type
• Date/time

The administrator controls bid-price and bidder-name visibility from Auction > Settings.

Customer Auction Account

My Bids

Logged-in customers can access My Account > My Bids. This page allows customers to view auctions they have participated in.

Information can include:

• Auction/product
• Customer's maximum bid
• Current highest bid
• Bid status
• Winning status
• Outbid status

Won Auctions

Customers can access My Account > Won Auctions. This page displays completed auctions won by the customer.

Information includes:

• Auction/product
• Winning status
• Final price
• Completed auction information

Automatic Winner Selection

When cron processes an expired auction, the system performs the following process:

Lock Auction

Auction and related bid records are locked for processing.

Find Highest Valid Bid

The system identifies the highest valid bid.

Check Reserve

The effective reserve price is checked.

Save Winner

If the reserve is met, the winner and final price are stored.

End Auction

The auction status changes to Ended.

Send Notifications

Enabled winner and admin notifications are sent.

No Winner

If no valid bids exist or the reserve price is not met, the auction ends without a winner.

Email Notifications

The extension supports the following notification types:

• Winner email to customer
• Winner email to admin
• Manual outbid email
• Automatic/Proxy outbid email
• Custom automatic outbid message

Email delivery depends on the OpenCart mail configuration.

Admin Auction Management

Auction Management

Administrators can manage auctions from Auction > Auctions.

The administrator can:

• Add auctions
• Edit auctions
• View auctions
• Delete auctions
• Monitor auction status

The auction list displays information such as:

• Product
• Starting price
• Start date
• End date
• Auction status

Bid Management

Administrators can click the Bids button for an auction to monitor:

• Customer
• Customer email
• Bid amount
• Proxy maximum
• Manual/Proxy bid type
• Bid date/time

The Bids screen is intended for monitoring and does not provide bid amount editing.

Auction Settings

The Auction > Settings page controls:

License

• License status
• License key

Buy It Now

• Buy It Now availability
• Add to Cart behavior

Auction Display

• Current bid visibility
• Bidder-name visibility
• Product status
• Regular-price display
• Bid-history visibility

Bidding

• Fixed increments
• Tiered increments
• Automatic bidding
• Proxy bidding behavior

Reserve

• Reserve status
• Reserve behavior

Notifications

• Customer winner notification
• Admin winner notification
• Manual outbid notification
• Automatic/proxy outbid notification
• Automatic outbid message

Cron-Based Auction Processing

Purpletree Auction registers its background task with a one-minute cycle. The server must execute OpenCart's main cron.php regularly.

Cron is required for:

• Scheduled auction activation
• Auction expiration
• Winner selection
• Final price processing
• Auction status updates
• Background notifications where applicable

Without cron, an auction page may show that its time has expired while background processing such as winner selection or scheduled activation is delayed.

Installation and System Requirements

System Requirements

• OpenCart: 4.x
• PHP: 8.1 or newer
• Database: MySQL / MariaDB
• PHP cURL: Required for license validation
• Cron: Required for scheduled activation and winner selection
• Mail Transport: Required for email notifications

Installation

Purpletree Auction can be installed using the OpenCart Extension Installer or through manual installation.

During installation, the extension creates and configures the required auction database tables, auction bid tables, admin permissions, storefront/admin events, minute-based cron registration, and required extension configuration.

License Configuration

A valid license is required outside localhost. Localhost is allowed for development and testing.

After installation, the license can be configured from Auction > Settings by enabling License Status, entering the Purpletree Auction license key, applying the license key, and saving the configuration.

The license key is validated by the server before the configuration is saved.

Creating an Auction

There are two supported methods for creating an auction.

Auction Management

Administrators can go to Auction > Auctions, click Add, select the required product, enter the auction details, configure the start and end time, enable Status, and save the auction.

Product Form

The extension also adds an Auction tab to the OpenCart product form when the module and license are active.

Administrators can go to Catalog > Products, open an existing product or create a new product, open the Auction tab, enter the required auction details, configure the start and end time, and save the product.

Important: Use only one current scheduled or active auction per product.

Uninstallation

Uninstalling Purpletree Auction removes its registered events, cron configuration, and auction database tables.

Before uninstalling the extension, export required auction data, back up the database, back up store files, and confirm that auction and bid data is no longer required.

Uninstallation may permanently remove auction-related data.

Production Requirements

Before moving the extension to production, verify the following:

• Complete store backup created
• Database backup created
• OpenCart 4.x compatibility confirmed
• PHP 8.1+ confirmed
• PHP cURL enabled
• Extension installed successfully
• License activated
• Auction menu visible
• Auction settings configured
• Cron configured for every minute
• Auction creation tested
• Manual bidding tested
• Minimum increment tested
• Proxy bidding tested
• Reserve price tested
• Buy It Now tested
• Auction expiration tested
• Winner selection tested
• My Bids tested
• Won Auctions tested
• Email notifications tested
• Normal product/cart flow regression tested
• Error logs checked

Purpletree Auction for OpenCart 4.x

Purpletree Auction provides a complete auction workflow for OpenCart 4.x, including auction creation, pricing, bidding, proxy bidding, reserve-price handling, Buy It Now, countdowns, customer bidding history, winner selection, and automated cron processing.

For production use, the most important configuration requirements are a valid license, correct auction settings, working OpenCart cron, correct server/OpenCart timezone, valid mail/SMTP configuration for notifications, and complete testing using dedicated test auctions before production deployment.