> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sponsored listings on category pages

The examples on this page show how to run [auctions](/en/ad-server/auctions/auctions-api) for products belonging to specific [categories](/en/ad-server/catalog/product-feed).

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.

<Note>
  **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.
</Note>

## 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](/en/api-reference/catalog-api/upsert-products). |
| 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

<Note>This field is plural. It's called `ids`, not `id`.</Note>

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")

```json theme={null}
{
  "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

<Warning>
  **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.
</Warning>

If the bids targeting products in the appropriate categories exist, a response to any of the above requests could look something like this:

```json theme={null}
{
  "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](/en/api-reference/examples/sponsored-listings/combining-results) for an example.