Search

To display sponsored listings on search results, send a request containing product IDs to Topsort. They will hold auctions for eligible products and return winners based on available ad slots. Eligible products are active campaigns with available vendor balances. You can also add geoTargeting and internal quality scores in the auction request.

The response will contain ranked auction results (up to 5 auctions per request) and indicate auction success with a boolean variable called "error". An example auction request and response are provided in JSON format. Note that up to 5 auctions requests in one API call are considered as a single auction request.

Request Example

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": [
          "p_PJbnN",
          "p_ojng4",
          "p_8VKDt",
          "p_Mfk15"
        ]
      },
      "geoTargeting": {
        "location": "New York"
      }
    }
    }
  ]
}

Response Example

The response contains auction results ranked up to 5 auctions per request, and will be empty if there are no winners or an error occurred. The boolean variable "error" indicates if the auction was successful. Below is an example of the response for one auction request using API V2 in JSON format.

{
  "results": [
    {
      "winners": [
           // winner details
      ],
      "error": false
    },
  ]
}