REST API

Auction-specific REST endpoints under /wp-json/wkafw/v1/. Built on the WP REST API and works with standard WordPress authentication.

Authentication

Public reads (see below) work without authentication. Everything else requires a logged-in WordPress user with the appropriate capability.

WP REST API auth docs →

Endpoints

Auctions

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

• {id} accepts either the auction row ID or the WooCommerce product ID — both resolve to the same auction.
• Public read: unauthenticated callers may list auctions (restricted to status=active) and read a single auction. Authenticated users may query any status.
• Create/update/delete require a user who can manage auctions (admin).

Sample auction response

{
  "id": 12,
  "product_id": 6311,
  "title": "Webkul Pulse Smartwatch",
  "auction_type": "standard",
  "start_price": 100.00,
  "reserve_price": 450.00,
  "buy_now_price": 899.00,
  "current_price": 100.00,
  "bid_increment": 25.00,
  "increment_type": "fixed",
  "status": "active",
  "start_date": "2026-09-10 08:00:00",
  "end_date": "2026-09-13 20:00:00",
  "anti_snipe_window": 60,
  "anti_snipe_extension": 120,
  "bid_count": 0
}

Create an auction

POST /wp-json/wkafw/v1/auctions
X-WP-Nonce: <nonce>
Content-Type: application/json

{
  "title": "Vintage Rolex Submariner",
  "product_id": 456,
  "auction_type": "standard",
  "start_price": 1000,
  "bid_increment": 50,
  "start_date": "2026-05-10 00:00:00",
  "end_date": "2026-05-15 18:00:00"
}

Returns 201 Created with the new auction object. DELETE returns { "deleted": true, "id": 12 }.

Auction bids

Bids are a sub-resource of an auction (there is no top-level /bids route).

GET    /wkafw/v1/auctions/{id}/bids            # bid history for one auction
GET    /wkafw/v1/auctions/{id}/bids?public=1   # public: masked bidder names
POST   /wkafw/v1/auctions/{id}/bids            # place a bid (logged-in)

Place a bid

POST /wp-json/wkafw/v1/auctions/12/bids
X-WP-Nonce: <nonce>
Content-Type: application/json

{
  "amount": 200
}

Response (success):

{
  "success": true,
  "bid_id": 4567,
  "auction_id": 12,
  "bid_amount": 200,
  "bid_date": "2026-05-14 15:30:00",
  "message": "Bid placed successfully."
}

Response (rejected):

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

Disputes

GET    /wkafw/v1/disputes                  # list disputes (admin, read-only)

Pagination

List endpoints support standard WP REST pagination:

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

Response headers:

• X-WP-Total: 11
• X-WP-TotalPages: 6

per_page is capped at 100.

Filtering

GET /wkafw/v1/auctions?status=active

• status — active, scheduled, ended, failed, or paused. Unauthenticated callers are always limited to active.

Errors

Standard WP REST error format:

{
  "code": "wkafw_auction_not_found",
  "message": "Auction not found.",
  "data": { "status": 404 }
}

Common codes:

Hooks

// Allow unauthenticated read access to auction/bid read endpoints.
apply_filters( 'wkafw_rest_public_read', $allow ); // default true

To add your own endpoint, register it normally on rest_api_init:

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

Common questions

"Can I list auctions without authentication?"

Yes — GET /wkafw/v1/auctions is public but returns status=active lots only. To query other statuses, authenticate.

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

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