Auctions

This page provides an overview of how to interact with the auctions resource in the Rankbid API. Auctions serve as the primary resource on Rankbid, allowing you to sell an item (whether digital or physical) by sharing the auction URL with potential bidders.

The auction model

The auction model contains all the information about the bidding period, the auction title and minimum bid value. Optionally, it can include the bids associated with the auction (see below for more details).

Properties

Name
auctionId
Type
uuid
Description
Unique identifier for the auction.
Name
createdAt
Type
date
Description
Date and time when the auction was created (ISO 8601).
Name
biddingPeriodStartsAt
Type
date
Description
Date and time when the bidding period starts (ISO 8601).
Name
biddingPeriodEndsAt
Type
date
Description
Date and time when the bidding period ends (ISO 8601).
Name
type
Type
string
Description
Type of auction. Possible values are asynchronous and repeated.
Name
minimumBidValueInCents
Type
int
Description
Minimum bid value in USD cents.
Name
title
Type
string
Description
Title of the auction set by the user at creation.
Name
status
Type
string
Description
Status of the auction. Possible values are upcoming, ongoing and completed.
Name
auctionUrl
Type
string
Description
URL where the bidders can place their bids.
Name
bids
Type
bid
Description
List of bids associated with the auction. This attribute is only present when includeBids is set to true in the request. Bids are not sorted in any particular order. See the bid model for more details on the attributes of bids.

GET/v1/auctions

List auctions

This endpoint allows you to retrieve a paginated list of all your auctions. By default, a maximum of 100 auctions are shown per page. Auctions are returned in descending order of creation date.

Optional parameters

Name
status
Type
string
Description
Filter auctions by status. Possible values are upcoming, ongoing and completed. By default, when no status filter is specified, all auctions are returned.
Name
includeBids
Type
boolean
Description
Whether to include the bids associated with the auction. Default value is false.
Name
limit
Type
int
Description
Maximum number of auctions to return. Default & maximum value is 100.
Name
offset
Type
int
Description
Number of auctions to skip. Default value is 0. See pagination for more details.

Request

GET

/v1/auctions

curl -G https://www.rankbid.io/api/v1/auctions \
    -H "Authorization: Bearer {api_key}" \
    -d "limit=100" \
    -d "offset=0" \
    -d "status=completed" \
    -d "includeBids=true"

Response

200

{
  "auctions": [
    {
      "auctionId": "8a76c57d-e802-4d3a-acf1-156d4ca2c161",
      "createdAt": "2024-07-19T17:11:03.107792+00:00",
      "biddingPeriodStartsAt": "2024-07-22T20:21:05.132+00:00",
      "biddingPeriodEndsAt": "2024-07-26T13:02:00+00:00",
      "type": "asynchronous",
      "minimumBidValueInCents": 79999,
      "title": "An example Rankbid auction",
      "status": "completed",
      "auctionUrl": "https://www.rankbid.io/auctions/8a76c57d-e802-4d3a-acf1-156d4ca2c161",
      "bids": [ // This attribute is only present when `includeBids` is set to `true`
        {
          "bidId": "f9bbf07d-62e8-413d-aa51-12a720615389",
          "placedAt": "2024-07-24T07:41:56+00:00",
          "bidderId": "bidder1@gmail.com",
          "bidValueInCents": 189000,
          "auctionId": "8a76c57d-e802-4d3a-acf1-156d4ca2c161",
          "isWinningBid": true
        },
        {
          "bidId": "3d3f5efa-190d-4a52-9d80-31ba773fb637",
          "placedAt": "2024-07-25T10:22:55.778689+00:00",
          "bidderId": "bidder2@gmail.com",
          "bidValueInCents": 79999,
          "auctionId": "8a76c57d-e802-4d3a-acf1-156d4ca2c161",
          "isWinningBid": false
        },
        // ...
      ]
    },
    {
      "id": "808b0493-ceec-445a-b3b0-a5632d3ff5da"
      // ...
    }
  ]
}

GET/v1/auctions/:auctionId

Get an auction by ID

This endpoint allows you to retrieve a specific auction by its unique identifier.

Optional parameters

Name
includeBids
Type
boolean
Description
Whether to include the bids associated with the auction. Default value is false.

Request

GET

/v1/auctions/:auctionId

curl -G https://www.rankbid.io/api/v1/auctions/8a76c57d-e802-4d3a-acf1-156d4ca2c161 \
    -H "Authorization: Bearer {api_key}" \
    -d "includeBids=true"

Response

200

{
  "auction": {
    "auctionId": "8a76c57d-e802-4d3a-acf1-156d4ca2c161",
    "createdAt": "2024-07-19T17:11:03.107792+00:00",
    "biddingPeriodStartsAt": "2024-07-22T20:21:05.132+00:00",
    "biddingPeriodEndsAt": "2024-07-26T13:02:00+00:00",
    "type": "asynchronous",
    "minimumBidValueInCents": 79999,
    "title": "An example Rankbid auction",
    "status": "completed",
    "auctionUrl": "https://www.rankbid.io/auctions/8a76c57d-e802-4d3a-acf1-156d4ca2c161",
    "bids": [ // This attribute is only present when `includeBids` is set to `true`
      {
        "bidId": "f9bbf07d-62e8-413d-aa51-12a720615389",
        "placedAt": "2024-07-24T07:41:56+00:00",
        "bidderId": "bidder1@gmail.com",
        "bidValueInCents": 189000,
        "auctionId": "8a76c57d-e802-4d3a-acf1-156d4ca2c161",
        "isWinningBid": true
      },
      {
        "bidId": "3d3f5efa-190d-4a52-9d80-31ba773fb637",
        "placedAt": "2024-07-25T10:22:55.778689+00:00",
        "bidderId": "bidder2@gmail.com",
        "bidValueInCents": 79999,
        "auctionId": "8a76c57d-e802-4d3a-acf1-156d4ca2c161",
        "isWinningBid": false
      },
        // ...
    ]
  }
}

POST/v1/auctions

Create an auction

This endpoint allows you to create a new auction. Once the auction is created, you can share the auctionUrl with potential bidders.

Required parameters

Name
biddingPeriod
Type
json
Description
JSON object containing 2 fields startTimestamp and endTimestamp representing the bidding period as unix timestamps. The startTimestamp must be at least 1 minute in the future when the server process the request, and endTimestamp must be after startTimestamp.
The maximum duration of the bidding period is 7 days, and the minimum duration is 1 hour. See Quickstart » Bidding period for more context on why these limits apply.
Name
title
Type
string
Description
Title of the auction that will be displayed to bidders. Must contain at least 3 characters and at most 150 characters.

Optional parameters

Name
minimumBidValueInCents
Type
int
Description
Minimum bid value in USD cents. The default & minimum value is 0 (not recommended), and the maximum value is 49999999.
Name
type
Type
string
Description
Currently, the default value is asynchronous and it is the only supported type of auction.

Request

POST

/v1/auctions

curl -X POST https://www.rankbid.io/api/v1/auctions \
    -H "Authorization: Bearer {api_key}" \
    -H "Content-Type: application/json" \
    -d '{
        "biddingPeriod": {
            "startTimestamp": 1728553727,
            "endTimestamp": 1728892125
        },
        "title": "An example Rankbid auction",
        "minimumBidValueInCents": 79999
    }'

Response

201

Created

{
  "auction": {
    "auctionId": "05b3be37-fb5c-4993-824f-149370ebb320",
    "createdAt": "2024-07-19T17:11:03.107792+00:00",
    "biddingPeriodStartsAt": "2024-10-10T09:48:45+00:00",
    "biddingPeriodEndsAt": "2024-10-10T09:48:45+00:00",
    "type": "asynchronous",
    "minimumBidValueInCents": 79999,
    "title": "An example Rankbid auction",
    "status": "upcoming",
    "auctionUrl": "https://www.rankbid.io/auctions/05b3be37-fb5c-4993-824f-149370ebb320"
  }
}

PATCH/v1/auctions/:auctionId

Update an auction

This endpoint allows you to update an upcoming or ongoing auction. When the auction is ongoing, you can only update the title and minimumBidValueInCents attributes.

Optional parameters

Name
title
Type
string
Description
Title of the auction that will be displayed to bidders. Must contain at least 3 characters and at most 150 characters.
Name
minimumBidValueInCents
Type
int
Description
Minimum bid value in USD cents. The minimum value is 0 (not recommended), and the maximum value is 49999999.
Name
biddingPeriod
Type
json
Description
This field can only be modified for upocoming auctions. It is a JSON object containing 2 fields startTimestamp and endTimestamp representing the bidding period as unix timestamps. The startTimestamp must be at least 1 minute in the future when the server process the request, and endTimestamp must be after startTimestamp.
The maximum duration of the bidding period is 7 days, and the minimum duration is 1 hour. See Quickstart » Bidding period for more context on why these limits apply.
If you provide the bidding period attribute, both timestamps must be provided.
Name
type
Type
string
Description
Currently, the only value supported is asynchronous. In the future, we will support the repeated auction type.

Request

PATCH

/v1/auctions/:auctionId

curl -X PATCH https://www.rankbid.io/api/v1/auctions/d21799f1-05a2-4e8f-9469-3f127bdbf34c \
    -H "Authorization: Bearer {api_key}" \
    -H "Content-Type: application/json" \
    -d '{
        "title": "An updated Rankbid auction",
        "minimumBidValueInCents": 99999
    }'

Response

200

{
    "auction": {
    "auctionId": "d21799f1-05a2-4e8f-9469-3f127bdbf34c",
    "createdAt": "2024-07-19T17:11:03.107792+00:00",
    "biddingPeriodStartsAt": "2024-10-10T09:48:45+00:00",
    "biddingPeriodEndsAt": "2024-10-10T09:48:45+00:00",
    "type": "asynchronous",
    "minimumBidValueInCents": 99999,
    "title": "An updated Rankbid auction",
    "status": "upcoming",
    "auctionUrl": "https://www.rankbid.io/auctions/d21799f1-05a2-4e8f-9469-3f127bdbf34c"
    }
}

DELETE/v1/auctions/:auctionId

Cancel an auction

This endpoint allows you to cancel an ongoing or upcoming auction. Once an auction is cancelled, it cannot be recovered. If the cancelled auction is ongoing, all payments authorization on bidders will be released without capturing any money. No communication is sent automatically to bidders when an auction is cancelled so we recommend you send an email to ensure the smoothest experience for bidders.

Request

DELETE

/v1/auctions/:auctionId

curl -X DELETE https://www.rankbid.io/api/v1/auctions/d21799f1-05a2-4e8f-9469-3f127bdbf34c \
    -H "Authorization: Bearer {api_key}"

Response

200

{ "success": true }