> For the complete documentation index, see [llms.txt](https://docs.auctionplusapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.auctionplusapp.com/admin-api/auction-items/place-a-bid.md).

# 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.

```json
{"openapi":"3.1.0","info":{"title":"Auction Plus API Documentation","version":"1.0.0"},"tags":[{"name":"Auction Items","description":"An auction item represents a single listing in an auction. Each item has a **status** of `scheduled`, `active`, or `completed`. Canceled auctions are indicated by a non-null **canceledAt** timestamp.\n\nPrice attributes such as **startPrice**, **reservePrice**, **minimumBid**, **currentIncrement**, and **highBidAmount** are returned as a price object containing **value** (minor units), **major**, **display**, and **currency** fields.\n\nThe **bidIncrementStrategy** describes the increment type — `fixed_amount`, `percentage`, or `tier` — along with a **value** object containing the increment details.\n\nThe **softClose** object indicates whether soft close is enabled. When active, **extendFrom** specifies how many seconds before the end time a bid triggers an extension, and **extendDuration** specifies how many seconds the auction is extended by.\n\nThe **processed** attribute indicates whether the auction listing has been finalized, including assigning a winner. Listings are typically processed within a minute after the end time."}],"servers":[{"url":"https://api.auctionplusapp.com/v1"}],"security":[{"http":[]}],"components":{"securitySchemes":{"http":{"type":"http","description":"You can retrieve your token by visiting Settings > API and clicking <b>Generate API token</b>.","scheme":"bearer"}},"schemas":{"AuctionItemResource":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"auction-items"},"attributes":{"type":"object","properties":{"startPrice":{"$ref":"#/components/schemas/Money"},"reservePrice":{"$ref":"#/components/schemas/Money"},"bidIncrementStrategy":{"$ref":"#/components/schemas/BidIncrementStrategy"},"automaticBidding":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]},"softClose":{"type":"object","properties":{"enabled":{"type":"boolean"},"extendFrom":{"type":["integer","null"]},"extendDuration":{"type":["integer","null"]}},"required":["enabled","extendFrom","extendDuration"]},"totalBids":{"type":"integer"},"highBidAmount":{"$ref":"#/components/schemas/Money"},"minimumBid":{"$ref":"#/components/schemas/Money"},"currentIncrement":{"$ref":"#/components/schemas/Money"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"status":{"type":"string"},"reserveMet":{"type":"string"},"canceledAt":{"type":["string","null"],"format":"date-time"},"archivedAt":{"type":["string","null"],"format":"date-time"},"processed":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}}},"required":["id","type"],"title":"AuctionItemResource"},"Money":{"type":"object","properties":{"value":{"type":"integer"},"major":{"type":"string"},"display":{"type":"string"},"currency":{"type":"string"}},"required":["value","major","display","currency"],"title":"Money"},"BidIncrementStrategy":{"type":"object","properties":{"strategy":{"type":"string"},"value":{"anyOf":[{"$ref":"#/components/schemas/FixedAmountBidIncrement"},{"$ref":"#/components/schemas/PercentageBidIncrement"},{"$ref":"#/components/schemas/TierBidIncrement"}]}},"required":["strategy","value"],"title":"BidIncrementStrategy"},"FixedAmountBidIncrement":{"type":"object","properties":{"amount":{"type":"object","properties":{"value":{"type":"integer"},"major":{"type":"string"},"display":{"type":"string"},"currency":{"type":"string"}},"required":["value","major","display","currency"]}},"required":["amount"],"title":"FixedAmountBidIncrement"},"PercentageBidIncrement":{"type":"object","properties":{"percentage":{"type":"number"}},"required":["percentage"],"title":"PercentageBidIncrement"},"TierBidIncrement":{"type":"object","properties":{"tier":{"type":"string"}},"required":["tier"],"title":"TierBidIncrement"},"BidResource":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"bids"},"attributes":{"type":"object","properties":{"amount":{"$ref":"#/components/schemas/Money"},"placedAt":{"type":["string","null"],"format":"date-time"},"automatic":{"type":["boolean","null"]}}}},"required":["id","type"],"title":"BidResource"},"CustomerResource":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"customers"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"registeredAt":{"type":["string","null"],"format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"bannedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"}}}},"required":["id","type"],"title":"CustomerResource"}},"responses":{"AuthenticationException":{"description":"Unauthenticated","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","description":"The HTTP status code applicable to this problem, expressed as a string."},"code":{"type":"string","description":"An application-specific error code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"id":{"type":"string","description":"A unique identifier for this particular occurrence of the problem."},"title":{"type":"string","description":"A short, human-readable summary of the problem."},"source":{"type":"object","description":"An object containing references to the source of the error.","properties":{"pointer":{"type":"string"},"parameter":{"type":"string"},"header":{"type":"string"}}},"meta":{"type":"object","description":"A meta object containing additional information about the error."}},"required":["status","code","detail"]}}},"required":["errors"]}}}}}},"paths":{"/auction-items/{id}/place-bid":{"post":{"operationId":"placeBid","description":"Places a bid on an active auction item.\n\nYou must provide either **max_amount** for a maximum bid (automatic bidding), **amount** for a straight bid, or both.\n\n- **Straight bid** (`amount`): Places a single bid at the specified amount.\n- **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.\n- **Both** (`amount` + `max_amount`): Places a straight bid at the specified amount and sets a proxy maximum for automatic bidding.\n\nThe 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.","summary":"Place a bid","tags":["Auction Items"],"parameters":[{"name":"fields[auction-items]","in":"query","description":"Available values are `startPrice`, `reservePrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `status`, `reserveMet`, `canceledAt`, `archivedAt`, `processed`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.","schema":{"type":"string"}},{"name":"fields[bids]","in":"query","description":"Available values are `amount`, `placedAt`, `automatic`. You can include multiple values by separating them with a comma.","schema":{"type":"string"}},{"name":"fields[customers]","in":"query","description":"Available values are `name`, `email`, `registeredAt`, `approvedAt`, `bannedAt`, `createdAt`. You can include multiple values by separating them with a comma.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"The auction item UID.","schema":{"type":"string"}},{"name":"include","in":"query","description":"Comma-separated list of related resources to include in the response. Available values: `highBid`, `highBid.customer`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"The customer UID."},"amount":{"type":["number","null"],"description":"The bid amount in major currency units (e.g. 10.50).","minimum":0},"maxAmount":{"type":["number","null"],"description":"The maximum (proxy) bid in major currency units (e.g. 10.50).","minimum":0}},"required":["customerId"]}}}},"responses":{"200":{"description":"`AuctionItemResource`","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/AuctionItemResource"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"highBid":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","enum":["bids"]},"id":{"type":"string"}},"required":["type","id"]}}}}}}}]},"included":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/BidResource"},{"$ref":"#/components/schemas/CustomerResource"}]}},"meta":{"type":"object","properties":{"status":{"type":"string","enum":["outbid","high_bidder"]}},"required":["status"]}},"required":["data","meta"]}}}},"401":{"$ref":"#/components/responses/AuthenticationException"},"403":{"description":"The provided user does not have access to this resource.","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","description":"The HTTP status code applicable to this problem, expressed as a string."},"code":{"type":"string","description":"An application-specific error code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"id":{"type":"string","description":"A unique identifier for this particular occurrence of the problem."},"title":{"type":"string","description":"A short, human-readable summary of the problem."},"source":{"type":"object","description":"An object containing references to the source of the error.","properties":{"pointer":{"type":"string"},"parameter":{"type":"string"},"header":{"type":"string"}}},"meta":{"type":"object","description":"A meta object containing additional information about the error."}},"required":["status","code","detail"]}}},"required":["errors"]}}}},"422":{"description":"The bid could not be placed. Inspect `errors[0].code` for the specific reason:\n\n- `user_not_found` — customer was not found for the given `customerId`.\n- `auction_ended` — the auction has already ended.\n- `amount_below_start_price` — the straight bid `amount` is below the auction's start price.\n- `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.\n- `max_amount_below_start_price` — the max bid `maxAmount` is below the auction's start price. `meta.minimum_bid` shows the start price.\n- `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.\n- `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.","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","description":"The HTTP status code applicable to this problem, expressed as a string."},"code":{"type":"string","description":"An application-specific error code."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"id":{"type":"string","description":"A unique identifier for this particular occurrence of the problem."},"title":{"type":"string","description":"A short, human-readable summary of the problem."},"source":{"type":"object","description":"An object containing references to the source of the error.","properties":{"pointer":{"type":"string"},"parameter":{"type":"string"},"header":{"type":"string"}}},"meta":{"type":"object","description":"A meta object containing additional information about the error."}},"required":["status","code","detail"]}}},"required":["errors"]}}}}}}}}}
```