How to run an auction for a set of products
In this example we will use the API to run an auction for a set of products.
Only bids that target the products in this set will have a chance to win this auction. Bids that target other products will not participate.
This allows you full control over which products get shown where, while still enabling your vendors to promote products.
We don’t prescribe how you create your set of products, you can use any algorithm you desire. All we need is a list of product IDs.
For example, use your own algorithm to generate:
Collect the resulting IDs and pass them to an auction.
Your vendors will then be able to bid for opportunities to appear in valuable positions in the marketplace.
Let’s assume we use some kind of algorithm to create a set of product IDs. We can then pass them to an auction request:
The request above will create a single listings auction:
slots
field.products.ids
is the set of products. These need to exist in your catalog.As said before, only bids that target these products will participate in the auction.
The auction endpoint supports up to 10000 product IDs per auction, but we recommend sending no more than the 500 most relevant.
You may sometimes want to incorporate custom quality scores for each product. The quality score is a number between 0 and 1 that encodes the relevance of the participating products. The use of quality scores helps mitigate risks and losses due to non-relevant products winning auctions.
To include custom quality scores in the request, modify the products
field as shown below:
In this example:
p_PJbnN
has a quality score of 0.5
.p_ojng4
has a quality score of 0.4
.p_8VKDt
has a quality score of 0.7
.p_Mfk15
has a quality score of 0.6
.Important: The number of quality scores must match the number product IDs. If they do not match, the request will fail.
Caveat: You cannot include quality scores and a search query. While running an auction with a search query and a set of products is allowed, the request cannot include custom quality scores.
Do not cache this response or its results. Auctions need to be unique per page view, this is what makes the system work.
If the auction results are cached, the same results could be shown to multiple users or to the same user multiple times.
If bids targeting the products exist, they could win this auction. The resulting response would look something like this:
Notable here:
product
, because we’re running a listings auction.id
correspond to a product ID in the request.slots
field in the request.The winners will need to be combined with product data to create a result that can be shown to the end-user.
Check this page for an example.
How to run an auction for a set of products
In this example we will use the API to run an auction for a set of products.
Only bids that target the products in this set will have a chance to win this auction. Bids that target other products will not participate.
This allows you full control over which products get shown where, while still enabling your vendors to promote products.
We don’t prescribe how you create your set of products, you can use any algorithm you desire. All we need is a list of product IDs.
For example, use your own algorithm to generate:
Collect the resulting IDs and pass them to an auction.
Your vendors will then be able to bid for opportunities to appear in valuable positions in the marketplace.
Let’s assume we use some kind of algorithm to create a set of product IDs. We can then pass them to an auction request:
The request above will create a single listings auction:
slots
field.products.ids
is the set of products. These need to exist in your catalog.As said before, only bids that target these products will participate in the auction.
The auction endpoint supports up to 10000 product IDs per auction, but we recommend sending no more than the 500 most relevant.
You may sometimes want to incorporate custom quality scores for each product. The quality score is a number between 0 and 1 that encodes the relevance of the participating products. The use of quality scores helps mitigate risks and losses due to non-relevant products winning auctions.
To include custom quality scores in the request, modify the products
field as shown below:
In this example:
p_PJbnN
has a quality score of 0.5
.p_ojng4
has a quality score of 0.4
.p_8VKDt
has a quality score of 0.7
.p_Mfk15
has a quality score of 0.6
.Important: The number of quality scores must match the number product IDs. If they do not match, the request will fail.
Caveat: You cannot include quality scores and a search query. While running an auction with a search query and a set of products is allowed, the request cannot include custom quality scores.
Do not cache this response or its results. Auctions need to be unique per page view, this is what makes the system work.
If the auction results are cached, the same results could be shown to multiple users or to the same user multiple times.
If bids targeting the products exist, they could win this auction. The resulting response would look something like this:
Notable here:
product
, because we’re running a listings auction.id
correspond to a product ID in the request.slots
field in the request.The winners will need to be combined with product data to create a result that can be shown to the end-user.
Check this page for an example.