Place a bid

Places a bid on an active auction item.

You must provide either max_amount 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 (max_amount): 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 + max_amount): 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

You can retrieve your token by visiting Settings > API and clicking Generate API token.

Path parameters

idstringRequired

The auction item UID.

Example: 1c6af60by54hzdmgxy5ab4ypw0

Query parameters

fields[auction-items]stringOptional

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

fields[bids]stringOptional

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

fields[customers]stringOptional

Available values are name, firstName, lastName, externalId, email, registeredAt, approvedAt, bannedAt, createdAt. You can include multiple values by separating them with a comma.

includestringOptional

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

Body

customerIdstringRequired

The customer UID.

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

Unauthenticated

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:

• user_not_found — customer was not found for the given customerId.
• 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 /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: 52

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

{
  "data": {
    "id": "cv4bpx1j2568d4pj8nhs21gjpm",
    "type": "auction-items",
    "attributes": {
      "startPrice": {
        "value": 100,
        "major": "1.00",
        "display": "$1.00",
        "currency": "USD"
      },
      "reservePrice": {
        "value": 1000,
        "major": "10.00",
        "display": "$10.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,
        "extendFrom": null,
        "extendDuration": null
      },
      "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-07-29T18:29:55.000000Z",
      "endsAt": "2026-07-29T19:29:55.000000Z",
      "position": null,
      "status": "active",
      "reserveMet": true,
      "canceledAt": null,
      "archivedAt": null,
      "processed": false,
      "createdAt": "2026-07-29T18:29:55.000000Z",
      "updatedAt": "2026-07-29T18:29:55.000000Z"
    },
    "relationships": {
      "highBid": {
        "data": {
          "type": "bids",
          "id": "text"
        }
      }
    }
  },
  "included": [
    {
      "id": "text",
      "type": "text",
      "attributes": {
        "amount": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "placedAt": null,
        "automatic": null
      }
    }
  ],
  "meta": {
    "status": "outbid"
  }
}