Bids

This page explains how to interact with bids on Rankbid. Bids are offers by bidders that are associated to an auction.

The bid model

When a bidder places an offer on an auction, a bid is created. Rankbid uses credit cards for bid payments, so every bid is backed by a payment authorization that confirms the bidder has sufficient funds. This guarantees you always get paid by the winning bidder while ensuring a smooth experience for bidders by not charging them until they win an auction and without requiring upfront deposits.

When an auction ends, Rankbid tries to capture the funds of the highest bidder. If the payment capture is successful, the auction is won by that bidder, and all other payment authorizations are released. In some very rare cases, the payment capture might fail, and so Rankbid falls back to the next highest bidder.

Properties

Name
bidId
Type
uuid
Description
Unique identifier for the bid.
Name
bidderId
Type
string
Description
A shared identifier between Rankbid and your business for the bidder. By default, this is the email address of the bidder. You can overwrite this behavior with an internal identifier for the bidder when sharing the auction URL to your bidders by adding the bidderId query parameter. For more details on bidder identification, see Quickstart » Sharing your auction
Name
placedAt
Type
date
Description
Date and time when the bid was placed & the payment authorized (ISO 8601).
Name
bidValueInCents
Type
int
Description
Gross value of the bid in USD cents. It is backed by a credit card payment authorization.
Name
auctionId
Type
uuid
Description
Unique identifier for the auction the bid is associated with.
Name
isWinningBid
Type
boolean
Description
Indicates if the bid is the winning bid for the auction once it is completed. If the auction is still ongoing, this property will be false for every bid, even the highest bid.

GET/v1/bids

List bids

This endpoint allows you to retrieve a paginated list of bids. You can filter the bids by auction ID, bidder ID, or both.

Optional parameters

Name
auctionId
Type
uuid
Description
Filter bids by the auction ID.
Name
bidderId
Type
string
Description
Filter bids by the bidder ID.
Name
limit
Type
int
Description
Maximum number of bids to return. Default & maximum value is 100.
Name
offset
Type
int
Description
Number of bids to skip. Default value is 0. See pagination for more details.

Request

GET

/v1/bids

curl -G https://www.rankbid.io/api/v1/bids \
    -H "Authorization: Bearer {api_key}" \
    -d "limit=100" \
    -d "offset=0" \
    -d "bidderId=bidder1@gmail.com"

Response

200

{
  "bids": [
    {
      "bidId": "4f224656-ea89-44fe-a7a2-ad33ba00bcfa",
      "auctionId": "5119f4a6-2598-4229-9c36-658ac60eb5a3",
      "bidderId": "bidder1@gmail.com",
      "bidValueInCents": 15490,
      "placedAt": "2024-09-11T09:47:56+00:00",
      "isWinningBid": true
    },
    {
      "bidId": "08b3be37-cb5c-4993-824f-149370ebb320",
      "auctionId": "fec167fc-84e5-4f0e-9b71-e3a92ecd30dd",
      "bidderId": "bidder1@gmail.com",
      "bidValueInCents": 244290,
      "isWinningBid": false,
      "placedAt": "2024-09-11T09:47:56+00:00"
    },
    // ...
  ]
}

GET/v1/bids/:bidId

Get a bid by ID

This endpoint allows you to retrieve a bid by its ID.

Request

GET

/v1/bids/:bidId

curl -G https://www.rankbid.io/api/v1/bids/4f224656-ea89-44fe-a7a2-ad33ba00bcfa \
    -H "Authorization: Bearer {api_key}"

Response

200

{
  "bid": {
    "bidId": "4f224656-ea89-44fe-a7a2-ad33ba00bcfa",
    "auctionId": "5119f4a6-2598-4229-9c36-658ac60eb5a3",
    "bidderId": "bidder@example.com",
    "bidValueInCents": 15490,
    "placedAt": "2024-09-11T09:47:56+00:00",
    "isWinningBid": true
    }
}