Skip to main content
The filter field narrows an auction 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.
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.

​
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

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

​
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

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 auction to black Nike shoes:
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 auction to two brands:
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 auction to a single material:
With a single attribute, and and or behave identically. We use and here to signal that adding another attribute will make the filter stricter. The Sponsored Brands endpoint supports the same filter object, with one difference: it sits alongside triggers rather than alongside the targeting fields.
See the Sponsored brands example for the full request and response.

​
Next steps