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 at least one of the categories of the 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"
          ]
        ]
      }
    }
  ]
}

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 the disjunction. The disjunctions are specified as string arrays in the category.disjunctions field.

Only bids that target products that are in large or medium categories can participate in this auction.

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.