=== Bidra Auctions for WooCommerce ===
Contributors: beautifulplugins
Tags: auction, woocommerce auction, bidding, auction plugin, bid
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.6
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn any WooCommerce product into a live auction with bidding, countdown timers, reserve prices, Buy It Now and automatic winner selection.

== Description ==

[**Bidra Auctions for WooCommerce**](https://beautifulplugins.com/plugins/bidra-auctions-for-woocommerce-pro/) adds a complete auction product type to your WooCommerce store. Create a listing, set a start price and an end time, and let your customers bid against each other. When the clock runs out the plugin picks the winner, emails them a payment link, and hands the order over to your normal WooCommerce checkout.

It is built in the WooCommerce way: auctions are real products, so your themes, payment gateways, shipping rules, taxes and reports all keep working exactly as they do today.

[**🚀 Upgrade to Pro**](https://beautifulplugins.com/plugins/bidra-auctions-for-woocommerce-pro/) | [**📄 Plugin Documentation**](https://beautifulplugins.com/docs/bidra-auctions-for-woocommerce/) | [**💻 Support**](https://beautifulplugins.com/support/)

### Everything you need to run an auction

* **Auction product type** — a first-class WooCommerce product type, right next to Simple and Variable.
* **Start price and bid increment** — decide where bidding opens and how much each new bid must add.
* **Reserve price** — set a hidden minimum. Bidders see whether the reserve is met, never the amount. An auction that ends below its reserve does not sell.
* **Buy It Now** — let an impatient buyer skip the auction entirely, and optionally withdraw the option once bidding starts.
* **Scheduled start and end times** — line up auctions in advance and let them open and close on their own.
* **Automatic winner selection** — when an auction ends, the highest bidder wins and is emailed a link to pay.
* **Winner-only checkout** — nobody but the winning bidder can buy a finished auction.

### A bidding experience customers understand

* **Live countdown timer** on the auction page and, optionally, throughout your shop.
* **Live bid updates** — the current bid and bid count refresh without a page reload, and pause while the tab is in the background.
* **Bid history tab** with every bid, the highest bid highlighted, and optional name masking for privacy.
* **Watchlist** — customers save the auctions they care about and find them again under My Account.
* **Clear bidding states** — "you are winning", "you have been outbid" and "you won" are always visible.
* **My Account → Auctions** with My bids, Winning, Won and Watchlist views, plus a pay-now button.

### Built-in email notifications

Every email uses the native WooCommerce email system, so it inherits your branding and can be customised or disabled under **WooCommerce → Settings → Emails**.

* New bid placed (to you)
* You have been outbid (to the previous highest bidder)
* You won the auction (to the winner, with a payment link)
* Auction finished (to you)
* Auction did not sell (to you)

### Manage everything from one screen

* **WooCommerce → Auctions** with Bids, Winners and Settings tabs.
* A searchable, sortable table of every bid ever placed, with single and bulk delete. Deleting a bid recalculates the auction from the bids that remain.
* A winners table showing who won what, for how much, and whether they have paid.
* Auction status column and a "filter by auction status" dropdown on the Products screen.

### Shortcodes

Drop these into any page, post or block:

* `[bafw_auctions]` — an auction grid. Accepts `limit`, `columns`, `orderby`, `order`, `status` and `category`.
* `[bafw_ending_soon_auctions]` — auctions closing soonest.
* `[bafw_future_auctions]` — auctions that have not opened yet.
* `[bafw_finished_auctions]` — auctions that have closed.
* `[bafw_my_auctions]` — the auctions the logged-in customer has bid on.
* `[bafw_watchlist]` — the logged-in customer's watchlist.
* `[bafw_recent_bids]` — the most recent bids across the store.

### Developer friendly

* Templates load through `wc_get_template()`, so your theme can override any of them in `yourtheme/woocommerce/`.
* Documented actions and filters around bidding, auction lifecycle and display — see the Developer Documentation section below.
* HPOS (High-Performance Order Storage) and Cart & Checkout Blocks compatible.
* No bundled third-party libraries, no external requests and no tracking of any kind.

### Perfect for

* **Charity and fundraising sites** running benefit auctions
* **Collectibles, art and antiques dealers**
* **Car, equipment and machinery sales**
* **Liquidation and clearance stores**
* **Anyone who wants buyers to name the price**

== Installation ==

= Requirements =

* WordPress 6.2 or newer
* WooCommerce 7.0 or newer
* PHP 7.4 or newer

= Automatic installation =

1. Go to **Plugins → Add New** in your WordPress admin.
2. Search for "Bidra Auctions for WooCommerce".
3. Click **Install Now**, then **Activate**.

= Manual installation =

1. Download the plugin ZIP file.
2. Go to **Plugins → Add New → Upload Plugin**.
3. Choose the ZIP file and click **Install Now**, then **Activate**.

= Creating your first auction =

1. Go to **Products → Add New** and give the product a title, description and image, exactly as you would for any other WooCommerce product.
2. In the **Product data** dropdown, choose **Auction**.
3. Open the new **Auction** tab and fill in the fields:
    * **Item condition** — optional label shown to bidders on the auction page.
    * **Start price** — the lowest amount the first bid may be.
    * **Bid increment** — the minimum amount each new bid must add to the current bid. Defaults to 1 when left empty.
    * **Reserve price** — optional hidden minimum. Bidders are told only whether the reserve has been met. An auction that ends below its reserve does not sell.
    * **Buy It Now price** — optional. Lets a buyer purchase immediately at this price. Leave empty to disable Buy It Now.
    * **Auction starts** — when bidding opens. Leave empty to start immediately.
    * **Auction ends** — when bidding closes and the highest bidder wins. Both dates use your site timezone.
4. Publish the product.

The auction is now live on the product page, with a countdown timer, the current bid and the bid form. When the end time is reached the plugin closes the auction, marks the highest bidder as the winner and emails them a link to pay through your normal WooCommerce checkout.

= Adding an auctions page =

1. Create a page — for example "Auctions" — and add the `[bafw_auctions]` shortcode to it.
2. Publish the page, then select it under **WooCommerce → Auctions → Settings → Auctions page**.

See the Shortcodes list in the Description for the other available shortcodes and their attributes.

= Configuring the plugin =

Store-wide rules live under **WooCommerce → Auctions → Settings**. The defaults work out of the box; adjust them as needed.

Catalog:

* **Auctions page** — the page that lists your auctions (the page holding the `[bafw_auctions]` shortcode).
* **Finished auctions** — show or hide closed auctions on the shop and category pages.
* **Scheduled auctions** — let shoppers preview auctions that have not opened yet.
* **Shop page** — keep auctions off the main shop page so they are not mixed with regular products. They stay available on their own page, on category pages and through the shortcodes.

Bidding:

* **Maximum bid amount** — the highest amount a single bid may be, to catch mistyped bids. Leave empty for no limit.
* **Buy It Now** — keep Buy It Now available after bidding has started, or withdraw it with the first bid.
* **Raising your own bid** — allow or block the current highest bidder from bidding against themselves.
* **Bidder privacy** — mask bidder names in the public bid history, for example `B*******e`.
* **Watchlist** — let customers save auctions to a watchlist under My Account.

Display:

* **Countdown in product lists** — show the countdown timer on shop and category pages as well as on the product page.
* **Live bid updates** — refresh the current bid without reloading the page.
* **Update interval** — how often the browser checks for a new bid (minimum 5 seconds). Longer intervals mean less load on your server.

Advanced:

* **Remove data on uninstall** — delete all auction data when the plugin is deleted. Off by default.

Auction emails are configured with the rest of your store emails under **WooCommerce → Settings → Emails**, where each auction email can be customised or disabled.

= Managing your auctions =

* **WooCommerce → Auctions → Bids** — every bid ever placed, searchable and sortable, with single and bulk delete. Deleting a bid recalculates the auction from the bids that remain.
* **WooCommerce → Auctions → Winners** — who won what, for how much, and whether they have paid.
* **Products** — an auction status column and a "filter by auction status" dropdown.
* **My Account → Auctions** — where your customers follow their own bids, wins and watchlist, and pay for an auction they have won.

== Frequently Asked Questions ==

= Does this work with my theme? =

Yes. Auctions are ordinary WooCommerce products, so they use your theme's product templates. Every piece of auction markup lives in an overridable template under `templates/`, which you can copy into `yourtheme/woocommerce/` and restyle.

= What happens when an auction ends? =

A background task runs every minute and closes auctions whose end time has passed. The highest bidder becomes the winner and receives an email with a link to pay. If nobody bid, or the reserve price was not met, the auction is marked as unsold and you are notified instead.

= What if WP-Cron is unreliable on my host? =

The plugin also checks an auction's state whenever its page is viewed or its live bid data is requested, so an auction always shows the correct status to a visitor even if the scheduled task is delayed.

= Can somebody else buy an auction that I won? =

No. Once an auction closes, only the winning bidder can add it to the cart and check out.

= Can the reserve price be seen by bidders? =

No. Bidders are told only whether the reserve has been met.

= Can I hide bidder names? =

Yes. Enable **Bidder privacy** under **WooCommerce → Auctions → Settings** and names appear as the first and last character only, for example `B*******e`.

= Can I bid on my own auction? =

No. Self bidding inflates the price artificially and is blocked by default. Developers can change this with the `bafw_can_bid_on_own_auction` filter.

= Does the plugin support automatic (proxy) bidding? =

Automatic (proxy) bidding, sealed-bid auctions, anti-sniping auto-extend, automatic relisting and payment deadlines are part of the Pro add-on. The free plugin covers standard ascending auctions end to end.

= Will my data be deleted if I remove the plugin? =

Only if you ask for it. Enable **Remove data on uninstall** in the settings before deleting the plugin, and the bid history, settings and auction meta are removed. Otherwise everything is left untouched.

== Screenshots ==

1. The Auction tab in the WooCommerce Product Data metabox.
2. A live auction on the storefront with countdown, current bid and bid form.
3. The bid history tab.
4. The bids management screen under WooCommerce → Auctions.
5. The winners screen showing payment status.
6. The plugin settings.
7. My Account → Auctions.

== Changelog ==

= 1.0.5 =
* Fix: Buy It Now purchases made through the WooCommerce Checkout block did not close the auction, so it kept running and could be bought again. Paid orders created in the admin now close the auction too.
* Fix: Sold auctions stayed "In stock". A paid or sold auction is now set to "Out of stock", and goes back in stock if its order is cancelled or refunded, or when the auction is reopened.
* Fix: Saving an auction closed by Buy It Now no longer reopens it when its original end date is still in the future.
* Fix: Guest Buy It Now purchases are now recorded as sold.
* New: "End auction now" and "Mark as sold" actions in the Auction tab and the Products list, to close an auction early or record a sale made outside the store.
* Dev: `AuctionProduct::is_sold()`, `Scheduler::end_now()`, `Scheduler::mark_sold_offline()` and the `bafw_auction_sold_offline` action.

= 1.0.4 =
* Fix: Bidra Auctions Pro promotions are no longer shown when Pro is active.
* Tweak: Admin notices are now shown to users who can manage options, and no longer depend on WooCommerce being active.

= 1.0.3 =
* New: Admin notices for announcements and offers, with "Remind Me Later" and "Dismiss" options.
* Tweak: Added Pro, documentation and support links to the plugin description.

= 1.0.1 =
* Fix: Auction start and end times were shifted by the site's UTC offset on sites whose timezone is not UTC, so auctions could open, close and display at the wrong time. Dates are now read in the site timezone.
* New: `bafw_local_to_timestamp()` helper for converting auction and bid dates to timestamps.
* Tweak: Updated the Pro feature list on the settings screen.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.5 =
Fixes Buy It Now not closing auctions with the Checkout block, marks sold auctions out of stock, and adds "End auction now" and "Mark as sold" actions.

= 1.0.4 =
Hides Pro promotions when Bidra Auctions Pro is active.

= 1.0.3 =
Adds dismissible admin notices for announcements and offers.

== Privacy Policy ==

Bidra Auctions for WooCommerce stores the following data on your own server, and never transmits it anywhere:

* **Bids** — the auction, the bidding user's ID, the bid amount and the time it was placed, stored in the `bafw_bids` database table.
* **Watchlists** — the IDs of the users watching each auction, stored as product meta.
* **Auction outcomes** — the winning bidder's user ID and the linked order, stored as product meta.

The plugin makes no external HTTP requests, loads no remote assets, sets no cookies and includes no analytics or tracking of any kind. Bid data is retained until you delete the bid, delete the auction, or uninstall the plugin with the "Remove data on uninstall" setting enabled.

== Developer Documentation ==

= Constants =

`BAFW_VERSION`, `BAFW_FILE`, `BAFW_PATH`, `BAFW_URL`, `BAFW_ASSETS_PATH`, `BAFW_ASSETS_URL`.

= Helper functions =

* `bafw_get_auction( $product )` — returns the `AuctionProduct` object, or `false` when the product is not an auction.
* `bafw_is_auction( $product )` — whether a product is an auction.
* `bafw_get_bidder_name( $user_id )` — the bidder name, masked when the setting is enabled.
* `bafw_get_max_bid_amount()` — the configured single-bid ceiling.
* `bafw_get_account_auctions_url( $view )` — URL of a My Account auctions view.
* `bafw_local_to_timestamp( $date )` — convert a stored auction or bid date (site timezone) into a Unix timestamp.
* `bafw_format_date( $date )`, `bafw_format_duration( $seconds )` — display helpers.
* `bafw_get_template( $name, $args )`, `bafw_get_template_html( $name, $args )` — load a plugin template.

= Actions =

* `bafw_loaded` — after the plugin has instantiated its classes.
* `bafw_installed` — after installation or an upgrade routine completes.
* `bafw_before_place_bid` — `( $auction, $amount, $user_id )` before a validated bid is stored.
* `bafw_bid_placed` — `( $bid_id, $auction, $amount, $user_id )` after a bid is recorded.
* `bafw_bidder_outbid` — `( $previous_bidder, $auction, $amount )` when a bidder is outbid.
* `bafw_bid_inserted` — `( $bid_id, $data )` after a bid row is written.
* `bafw_bid_deleted` — `( $bid_id, $bid )` after a bid row is removed.
* `bafw_auction_recalculated` — `( $auction )` after an auction is rebuilt from its bids.
* `bafw_auction_started` — `( $auction )` when bidding opens.
* `bafw_auction_closed` — `( $auction, $winner_id, $fail_reason )` when an auction closes.
* `bafw_auction_won` — `( $auction, $winner_id )` when an auction closes with a winner.
* `bafw_auction_failed` — `( $auction, $fail_reason )` when an auction closes unsold.
* `bafw_auction_paid_state_changed` — `( $auction, $paid, $order_id )`.
* `bafw_watchlist_toggled` — `( $auction_id, $user_id, $watching )`.
* `bafw_before_bid_form` / `bafw_after_bid_form` — `( $auction )` around the bid form.
* `bafw_product_data_panel` — `( $auction )` at the end of the admin auction panel.
* `bafw_after_settings_fields` — at the end of the settings form.
* `bafw_settings_saved` — after the settings are saved.

= Filters =

* `bafw_validate_bid` — `( $result, $auction, $amount, $user_id )` return a `WP_Error` to reject a bid.
* `bafw_minimum_bid` — `( $minimum, $auction )` the lowest acceptable next bid.
* `bafw_bid_increment` — `( $increment, $auction )`.
* `bafw_max_bid_amount` — `( $amount )` the single-bid ceiling.
* `bafw_can_bid_on_own_auction` — `( false, $auction, $user_id )` allow sellers to bid on their own listings.
* `bafw_is_purchasable` — `( $purchasable, $auction )`.
* `bafw_is_buy_now_available` — `( $available, $auction )`.
* `bafw_cart_item_price` — `( $price, $auction )`.
* `bafw_price_html` — `( $price_html, $auction )`.
* `bafw_add_to_cart_text` / `bafw_add_to_cart_url` — `( $value, $auction )`.
* `bafw_bidder_name` — `( $name, $user_id )`.
* `bafw_item_conditions`, `bafw_auction_statuses`, `bafw_account_auction_views` — the built-in option lists.
* `bafw_history_limit` — `( 25 )` how many bids the history tab lists.
* `bafw_shortcode_query_args` — `( $args, $atts )`.
* `bafw_ajax_auction_data` — `( $auctions, $auction_ids )` the live refresh payload.
* `bafw_auctions_per_cron_run` — `( 50 )` how many auctions each cron run processes.
* `bafw_admin_tabs`, `bafw_screen_ids` — extend the admin screens.

= Templates =

Copy any file from the plugin's `templates/` directory into `yourtheme/woocommerce/` to override it, keeping the same relative path. For example, `templates/single-product/auction-bid-form.php` becomes `yourtheme/woocommerce/single-product/auction-bid-form.php`.

== Support & Feedback ==

Found a bug or have an idea? Open a thread in the [support forum](https://wordpress.org/support/plugin/bidra-auctions-for-woocommerce/) or [contact us directly](https://beautifulplugins.com/contact/).

== Credits ==

Built and maintained by [BeautifulPlugins](https://beautifulplugins.com).
