REST API

Auction-specific REST endpoints under /wp-json/wkafw/v1/. Built on WP REST API; works with standard auth (Application Passwords, JWT, OAuth, cookies).

Authentication

All endpoints require authentication except the public read-only ones. Three options:

WP REST API auth docs →

Endpoints

Auctions

GET    /wkafw/v1/auctions                  # list all
GET    /wkafw/v1/auctions?status=active    # filter
GET    /wkafw/v1/auctions/{id}             # single
POST   /wkafw/v1/auctions                  # create
PUT    /wkafw/v1/auctions/{id}             # update
DELETE /wkafw/v1/auctions/{id}             # delete (admin only)

Sample response

{
  "id": 123,
  "product_id": 456,
  "title": "Vintage Rolex Submariner",
  "auction_type": "standard",
  "start_price": 1000.00,
  "reserve_price": 5000.00,
  "buy_now_price": 8000.00,
  "current_price": 5500.00,
  "bid_increment": 50.00,
  "increment_type": "fixed",
  "status": "active",
  "start_date": "2026-05-10T00:00:00Z",
  "end_date": "2026-05-15T18:00:00Z",
  "anti_snipe_window": 60,
  "anti_snipe_extension": 120,
  "bid_count": 12,
  "watchers_count": 23,
  "url": "https://yoursite.com/product/vintage-rolex/"
}

Bids

GET    /wkafw/v1/bids                      # list (admin only)
GET    /wkafw/v1/bids?auction={id}         # by auction
GET    /wkafw/v1/bids?user={id}            # by user (admin or self)
POST   /wkafw/v1/bids                      # place a bid
DELETE /wkafw/v1/bids/{id}                 # admin retract

Place a bid

POST /wp-json/wkafw/v1/bids
Authorization: Bearer <token>
Content-Type: application/json

{
  "auction_id": 123,
  "amount": 5550.00
}

Response (success):

{
  "id": 4567,
  "auction_id": 123,
  "user_id": 42,
  "amount": 5550.00,
  "status": "active",
  "placed_at": "2026-05-14T15:30:00Z",
  "auction": {
    "current_price": 5550.00,
    "bid_count": 13
  }
}

Response (rejected):

{
  "code": "wkafw_bid_below_increment",
  "message": "Bid must be at least $5,550.00",
  "data": { "status": 400 }
}

Watchlist

GET    /wkafw/v1/watchlist                 # list user's watches
POST   /wkafw/v1/watchlist                 # add (body: { auction_id })
DELETE /wkafw/v1/watchlist/{auction_id}    # remove

Wallet

GET    /wkafw/v1/wallet                    # balance + ledger
POST   /wkafw/v1/wallet/transfer           # peer transfer
POST   /wkafw/v1/wallet/withdrawal         # request payout

Auctions search

GET    /wkafw/v1/search?q=rolex&type=standard&status=active

Returns matching auctions with relevance scores.

Bidder profile

GET    /wkafw/v1/users/{id}                # public profile
GET    /wkafw/v1/users/me                  # current user

Stripe webhook (public — verified by signature)

POST   /wkafw/v1/stripe/webhook

Reports

GET    /wkafw/v1/reports/revenue?range=30
GET    /wkafw/v1/reports/top-bidders?limit=10
GET    /wkafw/v1/reports/conversion-funnel

Admin-only.

Pagination

List endpoints support standard WP REST pagination:

GET /wkafw/v1/auctions?page=2&per_page=20

Response headers:

• X-WP-Total: 543
• X-WP-TotalPages: 28

Filtering

GET /wkafw/v1/auctions?status=active&type=proxy&from=2026-05-01&to=2026-05-15

Common params:

• status — active / scheduled / ended / paid / failed
• type — auction type
• from / to — date range (ISO 8601)
• vendor_id — filter by vendor
• category — WC category slug
• search — text search

Sorting

GET /wkafw/v1/auctions?orderby=end_date&order=ASC

Supported orderby: id, start_date, end_date, current_price, bid_count, created_at.

Rate limiting

Default: 60 requests per minute per authenticated user. Configurable via wkafw_rest_rate_limit.

Rate limit headers in responses:

• X-Wkafw-RateLimit-Limit: 60
• X-Wkafw-RateLimit-Remaining: 47
• X-Wkafw-RateLimit-Reset: 1684089660

429 returned when exceeded.

Errors

Standard WP REST error format:

{
  "code": "wkafw_bid_below_increment",
  "message": "Bid must be at least $5,550.00",
  "data": {
    "status": 400,
    "min_amount": 5550.00,
    "current_price": 5500.00
  }
}

Common codes:

Hooks

apply_filters( 'wkafw_rest_endpoints',  $endpoints );
apply_filters( 'wkafw_rest_response',   $response, $endpoint );
do_action(    'wkafw_rest_request',    $endpoint, $request );

To add a custom endpoint:

add_action( 'rest_api_init', function() {
    register_rest_route( 'wkafw/v1', '/my-custom', [
        'methods'  => 'GET',
        'callback' => 'my_custom_handler',
        'permission_callback' => fn() => current_user_can( 'read' ),
    ] );
} );

SDK / clients

The plugin doesn't ship language-specific SDKs, but the API is OpenAPI-compatible. Generate clients with:

# Get the OpenAPI spec
curl https://yoursite.com/wp-json/wkafw/v1 -o spec.json

# Generate Python client
openapi-generator-cli generate -i spec.json -g python -o ./client

Or use the standard requests / axios libraries directly — the API surface is small enough.

Common questions

"Can I list all auctions without authentication?"

Yes — GET /wkafw/v1/auctions is public for status=active lots. To list all statuses (including drafts), authentication is required.

"How do I get bidding history without an account?"

Public endpoint: GET /wkafw/v1/auctions/{id}/bids?public=1 returns masked bidder names + amounts only.