Place a bid

Places a bid on an active auction item on behalf of the authenticated storefront customer.

You must provide either maxAmount for a maximum bid (automatic bidding), amount for a straight bid, or both.

• Straight bid (amount): Places a single bid at the specified amount.

• Proxy bid (maxAmount): Sets the maximum amount the system will automatically bid up to on behalf of the customer. The system places the minimum winning bid and automatically increments as competing bids are received, up to the maximum.

• Both (amount + maxAmount): Places a straight bid at the specified amount and sets a proxy maximum for automatic bidding.

The response returns the updated auction item with a meta.status field indicating whether the customer is the high_bidder or was automatically outbid by proxy bidding.

post

Authorizations

AuthorizationstringRequired

Your storefront (public) token, sent as Authorization: Bearer STOREFRONT_TOKEN. Generate one in Auction Plus under Settings > API, in the Storefront API section, by clicking Generate Public Token. Required on every request.

Path parameters

idstringRequired

The auction item UID.

Example: 1c6af60by54hzdmgxy5ab4ypw0

Query parameters

fields[auction-items]stringOptional

Available values are startPrice, bidIncrementStrategy, automaticBidding, softClose, totalBids, highBidAmount, minimumBid, currentIncrement, startsAt, endsAt, position, status, enableReserve, reserveMet, processed, createdAt, updatedAt, canceledAt. You can include multiple values by separating them with a comma.

fields[bids]stringOptional

Available values are amount, placedAt. You can include multiple values by separating them with a comma.

fields[max-bids]stringOptional

Available values are amount, createdAt. You can include multiple values by separating them with a comma.

fields[auction-winners]stringOptional

Available values are amount, notifiedAt, paymentDueAt. You can include multiple values by separating them with a comma.

viewerFieldsstringOptional

Comma-separated per-viewer fields to return under meta.viewer on the resource and any included resources. Available values: hasBid, isWatching, isHighBidder, isOwner. Requires an authenticated customer.

Example: hasBid,isWatching

includestringOptional

Comma-separated list of related resources to include in the response. Available values: highBid, highBid.customer, viewerMaxBid, viewerWin.

Body

amountnumber · nullableOptional

The bid amount in major currency units (e.g. 10.50).

maxAmountnumber · nullableOptional

The maximum (proxy) bid in major currency units (e.g. 10.50).

Responses

200

AuctionItemResource

application/vnd.api+json

401

The provided user does not have access to this resource.

application/vnd.api+json

403

The provided user does not have access to this resource.

application/vnd.api+json

422

The bid could not be placed. Inspect errors[0].code for the specific reason:

• access_denied — the customer is not permitted to bid (e.g. not approved for bidder registration).
• auction_ended — the auction has already ended.
• amount_below_start_price — the straight bid amount is below the auction's start price.
• amount_below_showing_bid — the straight bid amount is at or below the current high bid plus the required increment. meta.minimum_bid shows the minimum acceptable value.
• max_amount_below_start_price — the max bid maxAmount is below the auction's start price. meta.minimum_bid shows the start price.
• max_amount_below_showing_bid — the max bid maxAmount is at or below the current high bid plus the required increment. meta.minimum_bid shows the minimum acceptable value.
• max_amount_below_current_bid — the customer is already the high bidder and the new maxAmount is lower than their existing showing bid. meta.minimum_bid shows the existing bid amount.

application/vnd.api+json

post/auction-items/{id}/place-bid

POST /storefront/v1/auction-items/{id}/place-bid HTTP/1.1
Host: api.auctionplusapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "amount": null,
  "maxAmount": null
}

{
  "data": {
    "id": "pvrxnwvdgn2g14k4py4yqg36j4",
    "type": "auction-items",
    "attributes": {
      "startPrice": {
        "value": 100,
        "major": "1.00",
        "display": "$1.00",
        "currency": "USD"
      },
      "bidIncrementStrategy": {
        "strategy": "fixed_amount",
        "value": {
          "amount": {
            "value": 500,
            "major": "5.00",
            "display": "$5.00",
            "currency": "USD"
          }
        }
      },
      "automaticBidding": {
        "enabled": true
      },
      "softClose": {
        "enabled": false
      },
      "totalBids": 1,
      "highBidAmount": {
        "value": 5000,
        "major": "50.00",
        "display": "$50.00",
        "currency": "USD"
      },
      "minimumBid": {
        "value": 5500,
        "major": "55.00",
        "display": "$55.00",
        "currency": "USD"
      },
      "currentIncrement": {
        "value": 500,
        "major": "5.00",
        "display": "$5.00",
        "currency": "USD"
      },
      "startsAt": "2026-08-28T13:52:12.000000Z",
      "endsAt": "2026-08-28T14:52:12.000000Z",
      "position": null,
      "status": "active",
      "enableReserve": true,
      "reserveMet": true,
      "processed": false,
      "createdAt": "2026-08-28T13:52:12.000000Z",
      "updatedAt": "2026-08-28T13:52:12.000000Z",
      "canceledAt": null
    },
    "relationships": {
      "highBid": {
        "data": {
          "type": "bids",
          "id": "text"
        }
      },
      "viewerMaxBid": {
        "data": {
          "type": "max-bids",
          "id": "text"
        }
      },
      "viewerWin": {
        "data": {
          "type": "auction-winners",
          "id": "text"
        }
      }
    }
  },
  "meta": {
    "status": "outbid"
  }
}