Auctions

❗️

Deprecated

Auctions v1 is deprecated, please refer to auctions v2 instead.

API Version 1 runs completely on productId and resumes all relevance from the marketplace taxonomy. Only results that were originally part of the organic results will participate in the auctions. As you can see here in the API reference document for v1.

You can call Topsort's auctions either on specific categories and pages or as you'd like on where promoted products will be first rolled out.

The required variables here are slots , productId, and sessionId. Refer to our /auctions page for more information about these variables.

NameTypeDescription
slotsobjectHow many auction winners should be returned for each promotion type. The promotion types depend on the marketplace configuration. For sponsored listings, use the "listings" key.
productIdstringIDs of the products that will participate in the auction
sessionIdstringA single user (human) session for an unspecified period of time. Impressions, clicks and purchases from a single user must all share the same session ID in order for Topsort to correctly attribute clicks and purchases to an auction winner.

Request

This is an example of a request made using the API V1 in JSON format.

{
  "slots": {
    "listings": 2,
    "bannerAds": 1
  },
  "products": [
    {
      "productId": "p_SA0238",
      "quality": 0.75
    },
    {
      "productId": "p_SA0250",
      "quality": 0.9
    },
    {
      "productId": "p_SA0259",
      "quality": 0.7
    }
  ],
  "vendors": [
    {
      "vendorId": "v_SA0362"
    },
    {
      "vendorId": "v_SA0056"
    }
  ],
  "bannerOptions": {
    "placement": "Category-page"
  }
}

Response

You will get a response under "listings" with the winner productIDs. With that, you can design, render the label, and decide how to set up a sponsored listing.

This is an example of the response using the API V1 in JSON format.

{
  "slots": {
    "listings": {
      "auctionId": "AKFU78",
      "winners": [
         {
          "rank": 1,
          "productId": "pSA0238",
          "winnerType": "product",
          "winnerId": "b_Mfk15",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
          "assetUrl": "https://address.to/image.png"
        }
      ]
    }
  }
}