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.
| Name | Type | Description |
|---|---|---|
| slots | object | How 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. |
| productId | string | IDs of the products that will participate in the auction |
| sessionId | string | A 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"
}
]
}
}
}