Bidra Auctions Developer Reference — Hooks, Filters, Templates & REST API

Bidra Auctions is built to be extended — the Pro add-on itself uses only these public hooks. Text domain: bidra-auctions-for-woocommerce; namespace: BidraAuctionsForWooCommerce; function/hook/option prefix: bafw_; meta prefix: _bafw_; constants: BAFW_*.

Template overrides

All auction markup loads through wc_get_template(). Copy any file from the plugin’s templates/ directory into yourtheme/woocommerce/, keeping the same relative path:

templates/single-product/auction-bid-form.php
→ yourtheme/woocommerce/single-product/auction-bid-form.php

Folder	Templates
`single-product/`	`auction-bid-form.php`, `auction-countdown.php`, `auction-dates.php`, `auction-reserve.php`, `auction-watchlist.php`, `add-to-cart/auction.php`, `tabs/auction-history.php`
`loop/`	`auction-badge.php`, `auction-countdown.php`
`myaccount/`	`auctions.php`
`shortcodes/`	`recent-bids.php`
`emails/` and `emails/plain/`	`bafw-new-bid.php`, `bafw-outbid.php`, `bafw-auction-won.php`, `bafw-auction-finished.php`, `bafw-auction-failed.php`

Pro’s templates (auction-bid-form-sealed.php, auction-reserve-sealed.php, auction-pro-details.php, and the bafwp-* emails) override the same way.

Data model

Product type: auction, class BidraAuctionsForWooCommerce\Products\AuctionProduct (extends WC_Product). Always use its getters/setters — get_current_bid(), get_minimum_bid(), get_end_timestamp(), is_closed(), get_winner_id(), and so on.
Bid table: {$wpdb->prefix}bafw_bids — id, auction_id, user_id, bid, is_proxy, date_created.
Catalog taxonomy: auction_visibility with the terms finished, sold, buy-now, and future, used for fast catalog queries.
Dates: auction and bid dates are stored as site-local Y-m-d H:i:s strings. Convert them with bafw_local_to_timestamp() — never strtotime() or wc_string_to_timestamp(), which read them as UTC.
Price sync: _price and the wc_product_meta_lookup table follow the current bid.

Helper functions

Function	Returns
`bafw_get_auction( $product )`	The `AuctionProduct`, or `false` if not an auction.
`bafw_is_auction( $product )`	Whether a product is an auction.
`bafw_get_bidder_name( $user_id )`	Bidder name, masked when the setting is on.
`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 )`	Unix timestamp for a site-local date string.
`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

Action	Arguments	Fires
`bafw_loaded`	—	After the plugin instantiates its classes. Boot add-ons here.
`bafw_installed`	—	After install or an upgrade routine.
`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` / `bafw_bid_deleted`	`$bid_id, $data` / `$bid_id, $bid`	After a bid row is written / 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 (`no_bids` or `reserve_not_met`).
`bafw_auction_paid_state_changed`	`$auction, $paid, $order_id`	When the paid flag changes.
`bafw_watchlist_toggled`	`$auction_id, $user_id, $watching`	When a watchlist entry changes.
`bafw_before_bid_form` / `bafw_after_bid_form`	`$auction`	Around the bid form.
`bafw_product_data_panel`	`$auction`	End of the admin Auction tab — add your own fields.
`bafw_admin_tab_{tab}`	`$tab`	Render a custom tab on WooCommerce → Auctions.
`bafw_after_settings_fields` / `bafw_settings_saved`	—	Extend the settings form / react to saves.

Filters

Filter	Arguments	Use
`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`	Change the increment.
`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` / `bafw_is_buy_now_available`	`$value, $auction`	Purchase rules.
`bafw_cart_item_price` / `bafw_price_html`	`$value, $auction`	Pricing display.
`bafw_add_to_cart_text` / `bafw_add_to_cart_url`	`$value, $auction`	Button text and URL.
`bafw_bidder_name`	`$name, $user_id`	Bidder display name.
`bafw_item_conditions`, `bafw_auction_statuses`, `bafw_account_auction_views`	`$list`	Built-in option lists.
`bafw_history_limit`	`25`	Bids listed in the history tab.
`bafw_shortcode_query_args`	`$args, $atts`	Shortcode `WP_Query` arguments.
`bafw_ajax_auction_data`	`$auctions, $auction_ids`	Live-refresh payload.
`bafw_auctions_per_cron_run`	`50`	Auctions processed per cron run.
`bafw_admin_tabs`, `bafw_screen_ids`	`$list`	Extend the admin screens.

Example: require a billing phone before bidding

add_filter( 'bafw_validate_bid', function ( $result, $auction, $amount, $user_id ) {
    if ( is_wp_error( $result ) ) {
        return $result;
    }
    if ( ! get_user_meta( $user_id, 'billing_phone', true ) ) {
        return new WP_Error( 'needs_phone', __( 'Please add a phone number to your account before bidding.', 'my-plugin' ) );
    }
    return $result;
}, 10, 4 );

Pro hooks

Hook	Type	Arguments
`bafwp_loaded`	action	`$plugin` — Pro features booted (license valid).
`bafwp_auction_extended`	action	`$auction, $new_end, $bid_id` — anti-sniping extension.
`bafwp_bid_retracted`	action	`$auction, $user_id, $deleted`
`bafwp_auction_relisted`	action	`$auction, $previous_bidders`
`bafwp_second_chance_offer`	action	`$auction, $new_winner_id, $previous_winner_id`
`bafwp_settings_saved`	action	—
`bafwp_is_proxy_auction`	filter	`$is_proxy, $auction`
`bafwp_closing_soon_recipients`	filter	`$recipients, $auction`
`bafwp_rest_prepare_auction`	filter	`$data, $auction` — extend REST auction objects.
`bafwp_tasks_interval`	filter	Seconds between Pro background runs (default 900, minimum 300).

Pro background work (relisting, reminders, deadlines) runs on Action Scheduler in the bidra-auctions-pro group — inspect it under WooCommerce → Status → Scheduled Actions.

REST API (Pro)

Namespace bidra-auctions/v1. Read endpoints are public for published auctions; placing a bid requires an authenticated user (cookie + wp_rest nonce, or an application password).

Method & route	Parameters	Returns
`GET /wp-json/bidra-auctions/v1/auctions`	`status` (`running` default, `scheduled`, `finished`, `all`), `per_page` (1–100, default 10), `page`	Array of auctions.
`GET /wp-json/bidra-auctions/v1/auctions/{id}`	—	One auction.
`GET /wp-json/bidra-auctions/v1/auctions/{id}/bids`	`per_page` (1–100, default 25)	Bids, highest first: `id`, `bidder`, `amount`, `is_automatic`, `date`. Empty while a sealed auction runs.
`POST /wp-json/bidra-auctions/v1/auctions/{id}/bids`	`amount` (required)	`{ status, auction }`

An auction object includes id, name, permalink, type, proxy_bidding, status (running / scheduled / finished), condition, start_date, end_date, seconds_remaining, start_price, current_bid, bid_count, minimum_bid, bid_increment, has_reserve, reserve_met, buy_now_price, buy_now_available, is_sold, is_winning, and is_winner. On sealed auctions current_bid, bid_count, and reserve_met are null until the auction ends.

On proxy auctions the amount is the bidder’s maximum, and status is leading, outbid, or max_raised; otherwise it’s placed. A rejected bid returns a 400 error with the same message the bid form would show.

curl -X POST https://example.com/wp-json/bidra-auctions/v1/auctions/123/bids \
  -u "username:application-password" \
  -d amount=150