> ## 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.

# Filtering auctions by attributes

> How to narrow an auction to ads whose product attributes match specific key:value pairs

The `filter` field narrows an [auction](/en/ad-server/auctions/auctions-api) to ads whose products attributes match specific `key:value` pairs — a brand, a color, a material, a size, or any other attribute available at your marketplace. The attributes must be present on the marketplace catalog.

Use it when your page already knows something about what the shopper is looking at that your triggers can't express. A shoe search page with a "Nike only" facet applied, for example, shouldn't return sponsored listings for Adidas.

<Note>
  Attribute filtering requires additional integration and configuration. Your marketplace needs filterable attributes configured before the `filter` field has any effect — contact your Topsort representative to enable it.
</Note>

## How filtering differs from triggers

Triggers and filters do different jobs, and both apply to the same auction:

* **Triggers** (`products.ids`, `category`, `searchQuery`) select **which bids are eligible** to enter the auction.
* **`filter`** then **narrows that eligible set** by dropping ads whose attributes don't match.

Filtering happens **before ranking**. Ads that don't match are removed from the auction, so they can never win a slot and are never charged for an impression or a click.

The filter is combined with every other targeting field using AND. It can only ever narrow the set of participating bids — it never adds bids that your triggers excluded.

## The filter object

```json theme={null}
{
  "filter": {
    "operator": "and",
    "attributes": ["brand:nike", "color:black"]
  }
}
```

| Field        | Type            | Description                                                                                             |
| :----------- | :-------------- | :------------------------------------------------------------------------------------------------------ |
| `operator`   | string          | `and` keeps only ads that have **all** the listed attributes. `or` keeps ads that have **any** of them. |
| `attributes` | array of string | Up to 5 attributes in `key:value` format. Both the key and the value are limited to 40 characters.      |

### Choosing an operator

* Use **`and`** to be stricter. `["brand:nike", "color:black"]` with `and` keeps only ads for products that are both Nike **and** black.
* Use **`or`** to be broader. The same attributes with `or` keep ads for any Nike product **or** any black product.

<Note>
  A narrower filter means fewer participating bids, which means a higher chance of an auction returning no winners. If you see empty `winners` arrays after adding a filter, try `or` before assuming something is misconfigured.
</Note>

### Matching rules

* Attributes are matched as **exact strings**. `brand:nike` does not match `brand:Nike`, and does not match `brand:nike-air`. There is no wildcard, prefix, or case-insensitive matching.
* The `operator` value itself is case-insensitive, so `"AND"` and `"and"` both work. We recommend lowercase for consistency with the rest of the API.

### Limits and errors

| Condition                               | Result                                                                |
| :-------------------------------------- | :-------------------------------------------------------------------- |
| `operator` missing, or not `and` / `or` | `400` — the filter operator must be one of `and` or `or`              |
| `attributes` is an empty array          | `400` — provide at least one attribute                                |
| More than 5 attributes                  | `400` — a maximum of 5 attributes is allowed                          |
| An attribute matches no ad              | Not an error. The auction runs and may return fewer winners, or none. |

Omit the `filter` field entirely if you don't want to filter. There is no "match everything" value.

## Examples

### Filtering a set of products

Narrow a [set of products](/en/api-reference/examples/sponsored-listings/set-of-products) auction to black Nike shoes:

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"]
      },
      "filter": {
        "operator": "and",
        "attributes": ["brand:nike", "color:black"]
      }
    }
  ]
}
```

Only bids that target one of those four products **and** whose product is both Nike and black can win.

### Filtering a category page

Narrow a [category](/en/api-reference/examples/sponsored-listings/categories) auction to two brands:

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "laptop_bags"
      },
      "filter": {
        "operator": "or",
        "attributes": ["brand:targus", "brand:samsonite"]
      }
    }
  ]
}
```

Because the operator is `or`, an ad qualifies if it's a Targus bag **or** a Samsonite bag. Bags from other brands don't participate.

### Filtering search results

Narrow a [search](/en/api-reference/examples/sponsored-listings/search) auction to a single material:

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "searchQuery": "Running shoes",
      "filter": {
        "operator": "and",
        "attributes": ["material:mesh"]
      }
    }
  ]
}
```

With a single attribute, `and` and `or` behave identically. We use `and` here to signal that adding another attribute will make the filter stricter.

## Sponsored brands

The Sponsored Brands endpoint supports the same `filter` object, with one difference: it sits alongside `triggers` rather than alongside the targeting fields.

```json theme={null}
{
  "auctions": [
    {
      "winners": 2,
      "placementId": "some-placement",
      "triggers": {
        "searchQuery": "running shoes"
      },
      "filter": {
        "operator": "or",
        "attributes": ["brand:nike", "brand:adidas"]
      }
    }
  ]
}
```

See the [Sponsored brands example](/en/api-reference/examples/sponsored-brands) for the full request and response.

## Next steps

* [Run an auction for a set of products](/en/api-reference/examples/sponsored-listings/set-of-products)
* [Run an auction on a category page](/en/api-reference/examples/sponsored-listings/categories)
* [Run an auction on search results](/en/api-reference/examples/sponsored-listings/search)