Sponsored listings on category pages
The examples on this page show how to run auctions for products belonging to specific categories.
Only bids that target products belonging to the given categories will have a chance to win these auctions. Bids targeting products that belong to other categories will not participate.
Use cases
Running these kind of auctions on search pages will allow your vendors to promote products on category pages.
Non traditional categories:
Our catalog system does not make any assumption about what a category is.
If your marketplace deals with vacation homes for example, categories could be geographic locations instead of product groups.
Specifying categories
The /auctions
endpoint supports several ways to specify categories.
When you create an auction, you must pick one of the following methods:
Method | Relevant field | Description |
---|---|---|
Single category | category.id | Bid targets must belong to the category. The id of category is the same value used when upsert product. |
All categories | category.ids | Bid targets must belong to all of the categories. |
Disjunctions | category.disjunctions | Bid targets must belong to one of the categories of each disjunction. |
Let’s look at some examples.
Example API calls
Request: Single category
{
"auctions": [
{
"type": "listings",
"slots": 2,
"category": {
"id": "laptop_bags"
}
}
]
}
The request above will create a single listings auction that:
- Has a maximum of two winners due to the
slots
field. - Only allows bids that target products in a single category. The category ID is specified in the
category.id
field.
In this case, only bids that target products in the laptop_bags
category can take part in the auction.
Request: All categories
{
"auctions": [
{
"type": "listings",
"slots": 2,
"category": {
"ids": ["summer_hats", "sale"]
}
}
]
}
The request above will create a single listings auction that:
- Has a maximum of two winners due to the
slots
field. - Only allows bids that target products that belong to all categories. The category IDs are specified in the
category.ids
field.
This field is plural. It’s called ids
, not id
.
Only bids that target products that belong to both the summer_hats
and the sale
categories can take part in this auction.
Request: Disjunctions (“at least one category”)
{
"auctions": [
{
"type": "listings",
"slots": 2,
"category": {
"disjunctions": [
[
"large",
"medium"
],
[
"red",
"blue"
]
]
}
}
]
}
The request above will create a single listings auction that:
- Has a maximum of two winners due to the
slots
field. - Only allows bids that target products that belong to one of the categories for each disjunction. The disjunctions are specified as string arrays in the
category.disjunctions
field.
Only bids that target products that are in large
or medium
, and, red
or blue
categories can participate in this auction.
This means, products with the following combinations of categories:
large
andred
.large
andblue
.medium
andred
.medium
andblue
.
Response
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 the bids targeting products in the appropriate categories exist, a response to any of the above requests could look something like this:
{
"results": [
{
"winners": [
{
"rank": 1,
"type": "product",
"id": "p_Mfk15",
"resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
},
{
"rank": 2,
"type": "product",
"id": "p_PJbnN",
"resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
}
],
"error": false
},
]
}
Notable here:
- The type of the winners is
product
, because we’re running a listings auction. - There are two winners, the maximum that is allowed by the
slots
field in the request.
Next steps
The winners will need to be combined with product data to a create a result that can be shown to the end-user.
Check this page for an example.