Developer Reference

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.
bafw_price( $amount, $args )	Price HTML in the visitor’s currency. Pass 'convert' => false for the base currency (emails, admin). Use instead of wc_price().
bafw_price_text( $amount, $args )	Same as bafw_price() as plain text — no markup or HTML entities. Use for emails, notices and JavaScript.
bafw_display_amount( $amount, $auction ) / bafw_input_amount( $amount, $auction )	Convert base → visitor currency / visitor → base currency (unchanged without a currency switcher).
bafw_get_posted_bid_amount( $auction, $key )	The submitted bid converted to the base currency; a bid matching the displayed minimum is never rejected by conversion rounding.
bafw_get_base_currency(), bafw_get_base_price_args(), bafw_get_currency_symbol( $currency )	Base currency code, wc_price() args for it, and a plain-text currency symbol.
bafw_get_base_price_decimals()	Decimals of the base currency — use it to round stored amounts (switchers filter wc_get_price_decimals()).
bafw_get_auction_seller_id( $auction ) / bafw_get_auction_vendor_id( $auction )	The user who sells an auction / the marketplace vendor who sells it (0 for store-owned auctions).
bafw_is_marketplace_active()	Whether a Dokan or WCFM Marketplace integration is loaded.
AuctionData::apply( $auction, $data )	Validate and apply auction settings (start_price, bid_increment, reserve_price, buy_now_price, start_date, end_date, item_condition); returns true or a WP_Error. Use it from any custom editor.

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_compat_loaded	$folder, $instance	After a third-party integration boots.
bafw_auction_data_applied	$auction, $data	After auction settings are validated and applied, before the product is saved.
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.
bafw_display_amount / bafw_input_amount	$amount, $auction	Currency switcher integration: convert amounts for display / convert typed bids back to the base currency.
bafw_price_args	$args, $amount, $convert	wc_price() arguments used for auction amounts.
bafw_base_currency, bafw_base_price_args	$currency / $args	Base currency and its formatting.
bafw_curcy_convert_amount	true, $amount, $auction	Return false to stop CURCY converting a particular amount.
bafw_compat_integrations	$integrations	Register a third-party integration: folder => [ 'file', 'class', 'is_active' ].
bafw_validate_auction_data	$errors, $data	Add validation errors for auction settings (admin and vendor editors).
bafw_auction_seller_id / bafw_auction_vendor_id	$user_id, $auction_id	Map an auction to its seller / marketplace vendor.
bafw_marketplace_active	false	Declare a marketplace integration (shows “Notify the vendor” on the admin emails).
bafw_auction_email_recipient	$recipients, $email, $auction	Recipients of an auction email.
bafw_order_is_auction_source	true, $order, $auction	Whether an order settles (links, pays, closes) an auction it contains — return false for marketplace sub-orders.
bafw_dokan_vendor_auctions_enabled / bafw_wcfm_vendor_auctions_enabled	false	Let vendors edit auction settings in the Dokan / WCFM dashboard (Bidra Auctions Pro).

Currencies and currency switchers

Every bid, price and report is stored in the store’s base currency. Display amounts with bafw_price() / bafw_price_text() so they follow the WooCommerce currency settings and any switcher. To support another switcher, hook bafw_display_amount (base → visitor) and bafw_input_amount (visitor → base). CURCY – Multi Currency for WooCommerce is supported out of the box (includes/compat/woo-multi-currency/).

Third-party integrations

Integrations live in includes/compat/<plugin-slug>/ and are only included when the target plugin is active, so they cost nothing on other sites. The bafw_compat_loaded action ($folder, $instance) fires after each one boots.

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 );

New in 1.3.0

Listings

An auction that is restarted or relisted starts a new listing. Bids carry the listing they were placed in (listing column), and every query returns the current listing unless told otherwise.

API	Purpose
$auction->get_listing()	Listing number of the auction (0 until it is first restarted).
bafw_start_new_listing( $auction )	Starts a new listing; the caller resets the auction state and saves. Fires bafw_new_listing.
Bids::query( array( 'listing' => 'all' ) )	current (default), all, or a listing number. Also on Bids::count().
Bids::query( array( 'exclude_auctions' => array( 12, 34 ) ) )	Leave out the bids of some auctions.
Scheduler::restart( $auction, $duration ), Scheduler::extend( $auction, $seconds )	Fire bafw_auction_restarted and bafw_auction_extended.

Auction types that bid differently

Hook	Purpose
bafw_leading_bid (filter)	The bid that leads an auction; default the highest (Bids::get_leading()). Return Bids::get_lowest() for a reverse auction.
bafw_bid_direction (filter)	up or down; drives the bid form, quick bids, bid history order and the live refresh.
bafw_is_bid_amount_acceptable, bafw_bid_amount_error (filters)	The comparison against get_minimum_bid() and the error shown when it fails.
bafw_is_reserve_met (filter)	Whether the reserve has been met.
bafw_buy_now_price, bafw_buy_now_sale_price, bafw_auction_price (filters)	Instant purchase price, the price recorded for an instant sale, and the displayed auction price.
bafw_auction_bought_now (action)	An auction was closed by an instant purchase ($auction, $order).

Storefront

Hook	Purpose
bafw_bid_status, bafw_bid_status_labels (filters)	Where a user stands (winning, outbid, won, lost, or your own slug) and the labels. Helpers: bafw_get_bid_status(), bafw_get_bid_status_html().
bafw_badge_types, bafw_auction_badges (filters)	The badge types and the badges of one auction.
bafw_quick_bids, bafw_quick_bid_multipliers (filters)	The quick-bid amounts.
bafw_bid_flood_interval (filter)	Seconds between two bids by one user (default 2; 0 disables).
bafw_is_terms_consent_required (filter), bafw_terms_accepted (action)	Auction terms consent.
bafw_account_auction_ids (filter), bafw_account_auctions_view_{view}, bafw_account_auctions_before_table (actions)	My Account tabs: filter a tab’s auctions, render your own tab, print above the table.
bafw_recent_bids_query_args (filter)	The bid query of the recent bids list.
bafw_email_auction_details (action)	Print extra lines in the “won” email ($auction, $email, $plain_text).
bafw_structured_data_offer (filter)	The JSON-LD offer of an auction.
bafw_csv_columns, bafw_csv_export_value (filters), bafw_csv_import_row (action)	Extra CSV import/export columns.
bafw_auction_duplicated (action)	A duplicated auction was reset, before it is saved.

JavaScript

After every live refresh the storefront script dispatches a bubbling bafw:auction-data event on each auction container ([data-bafw-auction]), with the fresh data in event.detail:

document.addEventListener( 'bafw:auction-data', function ( event ) {
	if ( event.detail.bid_status === 'outbid' ) {
		// React to the bidder being outbid.
	}
} );

window.bafwFrontend.refresh() fetches fresh data immediately.

Example: a custom quick-bid ladder

add_filter( 'bafw_quick_bid_multipliers', function () {
	return array( 1, 3, 10 ); // Next bid, +2 increments, +9 increments.
} );

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).
bafwp_buyers_premium_rule, bafwp_buyers_premium, bafwp_buyers_premium_label	filter	Buyer’s premium rule, amount and label (1.3.0).
bafwp_is_approved_bidder, bafwp_credit_limit, bafwp_pickup_details, bafwp_event_slug	filter	Bidder approval, bidding limit, pickup details, event URL slug (1.3.0).
bafwp_bidder_status_changed, bafwp_combined_invoice_created, bafwp_event_registered, bafwp_event_schedule_applied	action	Bidder approval, invoices and events (1.3.0).

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

Related

• Pro Features
• FAQ & Troubleshooting