Website logo

Place a bid

Place a bid (normal or auto-bid) on a listing.

URL: https://api.trademe.co.nz/v1/Bidding/Bid.{file_format}
HTTP Method: POST
Requires Authentication? Yes
Permission Required: BiddingAndBuying: Place bids, and complete purchases using Buy Now & Fixed Price Offers.
Supported Formats: XML, JSON
Rate Limited? Yes

URL parameters

file_format Enumeration (required) The format of the response.
xml Serialize responses into XML.
json Serialize responses into JSON.

POST Data

<BidRequest>

ListingId Long Integer (required)

The listing ID of the item the bid is for.
Amount Number (required)

The bid amount, in New Zealand dollars.
AutoBid Boolean (required)

Indicates whether the bid is an auto-bid.
ShippingOption Long Integer (required)

The ID of the preferred shipping option which will be used when this request happens to be the winning bid. This ID can be retrieved from the ShippingId field in the listing detail.
EmailOutBid Boolean (optional)

Indicates whether the bidder should be emailed if they are outbid.
FirearmsLicence String (optional)

The user's firearms licence number. This is required for firearms purchases.
FirearmsLicenceHolder <FirearmsLicenceHolderDetails> (optional)

The user Enters First, Middle, and Last Names associated to the firearms licence.
FirstName String (required)

First name of Licence Holder. Required;
MiddleNames String (optional)

Middle Names of Licence Holder. Optional;
LastName String (required)

Last name of Licence Holder. Required;
IsBuyerOlderThan18 Boolean (optional)

The user agrees they are older than 18. This is required for wine purchases.
ReturnListingDetails Boolean (optional)

Indicates whether full listing details should be returned in the Listing field.
ReferringSearchQueryId String (optional)

The search query ID for the search which referred the user to the listing.

Returns

<AuctionBidResponse>

The details of the bid.

Success Boolean

Indicates whether the operation was successful.
Description String or null

The description of the error, if the operation failed.
IsTooHigh Boolean

Indicates whether the bid is too high.
IsTooLow Boolean

Indicates whether the bid is too low.
IsReserveMet Boolean

Indicates whether the reserve has been met.
MinimumNextBid Number

The minimum next bid price.
StatusCode Enumeration

The state of the bid.
Success 0

The bid was a success.
None 1

The bid had some other error.
ReserveMet 2

The reserve was met.
ErrorAccountDisabled 3

The buyer account is disabled.
ReserveNotMet 4

The reserve was not met.
ErrorBadMemberDetails 5

Not a member.
ReserveMetAutoBidGreaterThanReserve 6

The auto bid was higher than the reserve.
ErrorHeavyQuarantine 7

Needs proof of goods.
ReserveMetAutoBidIncreased 8

The autobid was increased.
ReserveNotMetAutoBid 9

An autobid did not met the reserve.
ReserveMetExistingAutoBidGreaterThanBid 10

Someone else has a higher bid which mets the reserve.
ErrorOwnAuction 11

This is an auction owed by the member.
ReserveNotMetExistingAutoBidGreaterThanBid 12

Someone else has a higher bid and the reserve is not met.
ErrorBlacklisted 13

The member has been blacklisted by the seller.
ReserveMetExistingAutoBidEqualToBid 14

The reserve is met and the auto bids match.
ErrorAuthenticatedMembersOnlyAuction 15

The member needs to be authenticated to bid.
ReserveNotMetExistingAutoBidEqualToBid 16

The reserve is not met and the auto bids match.
ErrorAccountIndebt 17

The accountis in debt and can not bid.
ReserveMetAutoBid 18

The reserve is met by an auto bid.
ErrorBidTooHigh 19

The bid is too high for our rules.
ErrorBidLessThanMinimumNextBid 21

The bid is too low.
ErrorBidLessThanFiftyCents 23

Bid needs to be higher than 50c.
ErrorBidLessThanStartPrice 25

The bid must be greater than the start price.
ErrorTooManyBids 27

There have been too many bids from the member in the last 24 hours.
ErrorHasTopAutoBid 29

The member already has the top autobid.
ErrorAuctionClosed 30

The auction is closed.
ErrorDatabase 31

There was an error in the database.
ErrorListingAcceptsBuyNowOnly 34

Attempting to bid on a listing that can't be bidded on.
ErrorQuantityInvalid 35

Quantity is either less than 1 or greater than the maximum.
ErrorListingIsAClassified 36

Attempting to bid on a classified listing.
ErrorInvalidShipping 37

Invalid shipping ID.
ErrorInvalidFirearmsLicense 38

Invalid or missing firearms license number.
ErrorAgeConfirmationRequired 39

Age confirmation is required for this listing.
ErrorListingAcceptsPayNowOnly 40

Attempting to buy a listing that can only be paid for by pay now
ErrorBuyProcessBan 41

Attempting to bid or buy now when member has been purchase banned.
AutoBidDecreased 42

The autobid was decreased.
Listing <ListedItemDetail> or null

The state of the listing, after the bid has been successfully placed. This field is only present if the ReturnListingDetails parameter is true and the bid operation was successful. This field will also be missing if there was an error retrieving the listing details. For more information on this field, see the documentation for the listing details API.
(This type is defined elsewhere)
CurrentAutoBid Number or null

If you are the bidder then the highest AutoBid value is returned

Example XML Request (switch to JSON) 

<BidRequest xmlns="http://api.trademe.co.nz/v1">
  <ListingId>123</ListingId>
  <Amount>123.0</Amount>
  <AutoBid>false</AutoBid>
  <ShippingOption>123</ShippingOption>
  <EmailOutBid>false</EmailOutBid>
  <FirearmsLicence>ABC</FirearmsLicence>
  <FirearmsLicenceHolder>
    <FirstName>ABC</FirstName>
    <MiddleNames>ABC</MiddleNames>
    <LastName>ABC</LastName>
  </FirearmsLicenceHolder>
  <IsBuyerOlderThan18>false</IsBuyerOlderThan18>
  <ReturnListingDetails>false</ReturnListingDetails>
  <ReferringSearchQueryId>ABC</ReferringSearchQueryId>
</BidRequest>

Example JSON Request (switch to XML) 

{
  "ListingId": 123,
  "Amount": 123.0,
  "AutoBid": false,
  "ShippingOption": 123,
  "EmailOutBid": false,
  "FirearmsLicence": "ABC",
  "FirearmsLicenceHolder": {
    "FirstName": "ABC",
    "MiddleNames": "ABC",
    "LastName": "ABC"
  },
  "IsBuyerOlderThan18": false,
  "ReturnListingDetails": false,
  "ReferringSearchQueryId": "ABC"
}

Example XML Response (switch to JSON) 

<AuctionBidResponse xmlns="http://api.trademe.co.nz/v1">
  <Success>false</Success>
  <Description>ABC</Description>
  <IsTooHigh>false</IsTooHigh>
  <IsTooLow>false</IsTooLow>
  <IsReserveMet>false</IsReserveMet>
  <MinimumNextBid>123.0</MinimumNextBid>
  <StatusCode>Success</StatusCode>
  <Listing> ... </Listing>
  <CurrentAutoBid>123.0</CurrentAutoBid>
</AuctionBidResponse>

Example JSON Response (switch to XML) 

{
  "Success": false,
  "Description": "ABC",
  "IsTooHigh": false,
  "IsTooLow": false,
  "IsReserveMet": false,
  "MinimumNextBid": 123.0,
  "StatusCode": 0,
  "Listing": { ... },
  "CurrentAutoBid": 123.0
}