# Factorize Auctions — Quickstart

Five minutes from install to an auction that runs itself.

## Prerequisites

- WordPress 6.2+ and PHP 7.4+
- **WooCommerce** (active)
- **Ultimate Auction for WooCommerce** (active) — it provides the `auction` product type, bid form, and bid processing that this plugin builds on. Without it, Factorize Auctions renders nothing.
- Working WP-Cron. Most hosts are fine out of the box; on a low-traffic site, point a real cron job at `wp-cron.php` so the hourly tick actually fires.

## Install

1. Copy the `factorize-auctions` folder into `wp-content/plugins/` (or upload the zip via Plugins → Add New).
2. Activate it. A **Factorize** menu appears in wp-admin — the Auctions card lives under the **Selling** tab and shows your current cycle length. The hourly `et_auction_tick` event schedules itself about five minutes later.

## First value in 4 steps

1. **Create an auction product** the usual Ultimate Auction way: opening price, bid increment, start/end dates, and (recommended) managed stock with the real unit count.
2. **Set the regular price — that is the Buy Now amount.** Ultimate Auction shows the active Buy Now button while bidding is below it; Factorize Auctions adds the grayed-out state (with an explanation) once bidding passes it. Leave the price empty for a pure auction.
3. **Add the honesty layer**: set an `_et_retail_price` custom field to get the "X% below retail" line (with its shopper-facing source link), and pick a **Returns** mode in Product data → General — the default is as-is for auctions, 7-day defect policy for regular products.
4. **Let it run.** From here the lifecycle is automatic: a failed cycle relists for a fresh cycle, a winner who never starts an order forfeits after the grace period, and a paid order (Buy Now or winning bid) relists the next unit — or ends the auction when the last one sells.

Shoppers get the rest for free: the one-tap quick-bid button, the billing-details bid gate, card extras on the shop page (Buy Now line, % below retail, ends-soon badge), and the folded "Condition, pickup & policies" fine print.

## Configuration

Overrides go in the `factorize-auctions_options` option (an array — override any subset of keys), and the merged config passes through the `factorize-auctions_config` filter. Read via `empire_auction_config( $key )`.

| Key | Default | Effect |
| --- | --- | --- |
| `relist_grace_days` | `3` | Days a winner gets to start an order before forfeiting; after that, the hourly tick relists the auction. |
| `fineprint_enabled` | `true` | When `false`, the "Condition, pickup & policies" fold is not rendered and the policy lines print unfolded. |
| `retail_source_template` | Google Shopping search | Where the "source" link on "% below retail" points; `{query}` becomes the URL-encoded product title. |

Related knobs outside that array:

| Where | Default | Effect |
| --- | --- | --- |
| `et_auction_days` option | `7` | Cycle length in days used when an auction relists. |
| `_et_retail_price` product meta | — | Pins the retail price; enables the "% below retail" line and card badge. |
| `_et_retail_source` product meta | — | Per-product source URL that overrides the search template. |
| `_et_returns_mode` product meta | default | The Returns dropdown on the product edit screen (`yes` / `no` / default). |

Example override:

```php
update_option( 'factorize-auctions_options', array( 'relist_grace_days' => 5 ) );
```

## Troubleshooting

- **Auctions never relist.** The lifecycle rides on WP-Cron's hourly `et_auction_tick`. If your site gets little traffic, WP-Cron may simply never fire — set up a real cron job hitting `wp-cron.php` (a plugin like WP Crontrol will show you whether the event is scheduled and when it last ran). Also note: after a *sale*, the next unit only relists when the product manages stock and quantity remains — with no managed stock, the first paid order ends the auction for good.
- **Nothing from this plugin shows on a product page.** Nearly every feature checks that the product type is `auction` — which only exists while Ultimate Auction for WooCommerce is active. A regular Simple product will only ever show the returns-policy line.
- **The "% below retail" line is missing.** It needs an `_et_retail_price` that is genuinely *above* the current basis (the highest bid, or the Buy Now price when nobody has bid). Equal or lower retail prices are suppressed on purpose — the plugin never prints a discount that is not real.
- **The quick-bid button does not appear.** It skips closed and out-of-stock auctions, and it needs Ultimate Auction's bid form on the page (the script moves the button into that form). If a theme or sibling defines an early-access gate (`empire_tools_auction_started_for_user`), the button also stays hidden until the auction opens for that user.

## Publishing note

`readme.txt` in this folder is the WordPress.org listing; the plugin's technical reference is `README.md`.
