Decision API Filtering

Prerequisites

The Decision API allows customers to filter ads based on a variety of criteria. These filters can be passed in the request to limit the returned ad results which allows platform clients to filter ad items based on their needs.

All filtering is based on the fields found within your catalog Item feed. To filter ad items properly, you must use the matching information found in your catalog. Please see our Catalog documentation for more information on catalog options, specifications, and requirements.

🚧

Caution

You may use up to 5 filtering criteria per decision request.

Multiple filtering criterias are considered in an AND relationship. An ad item must meet all of the filtering criterias in order to be displayed. For example, if a request specifies the category and location filtering criterias, the Decision API will only return ad items that are in the specified category and location.

The Decision API will return an empty response with a status code of 200 when:

• The filter combinations filter out all ad items.
• There are no active ad items that match the filtering criteria.

Supported Filters

MCM supports the following 15 filtering criterias when using the SSPI or MSPI catalog item feeds and 4 filtering criterias for the optional Seller Catalog.

Seller Catalog Filters

The MCM Seller Catalog Feed supports the following 4 filters, see the descriptions above for details.

Filter parameters

age_group

Returns ad items that exactly match any of the given values within the age_group field.

• age_group filtering supports 1 argument: age_group
• The filter applies OR logic to each value specified in the request.
  • The Decision API will return ad items that exactly match any of the age_group values provided.

Example:

“age_group”: {
    "age_groups”: ["all", "adult", "kids"]
}

brand

Returns ad items for a specific brand or brands found within the brand_id field.

• Brand filtering supports **1 **argument: brand_ids or brand_id.
• We recommended using the brand_ids argument for filtering, brand_id will remain for backwards compatibility.
  • Do not use both arguments in the same request.
• The brand filter applies OR logic to each value specified in the request.
  • When using brand_ids, the Decision API will return ad items that exactly match any of the brand id values provided in the request.
  • When using brand_id, the Decision API will return ad items that match the brand_id exactly.

Example:

“brand”: {
    “brand_ids”: ["brand1", "brand2"]
}

// brand_id (legacy)
"brand": {
    "brand_id": "brand"
}

category

Returns ad items matching the category field values.

• Category filtering uses 2 arguments as inputs: an operator and a list of categories.
  • The category argument may contain multiple category values and each category is a multi-depth value. The exact category depth used in the request must be present in the catalog item feed.
    • Example: To filter ad items based on the 2nd depth level of category A>B>C use A>B in the category filter.
    • Category: Bag/accessories>Women>Clutch/wallet
      Filter: Bag/accessories>Women
  • The operator supports 1 of 2 values OR or AND. The default value is OR.
    • The OR operator will return ad items that match any of the categories.
    • The AND operator will only return ad items that match all of the categories.

Example:

“category”: {  
    “operator”: “or”,  
    “categories”: [“A>B>C”, “X>Y>Z”],  
}

color

Returns ad items matching the color field values.

• Color filtering uses 1 argument: colors
• The filter applies OR logic to each value specified in the request.
  • The Decision API will return ad items that exactly match any of the color values.

color filtering example

“color”: {
    "colors”: ["red", "green", "blue"]
}

condition

Returns ad items matching the condition field values.

• Condition filtering uses 1 argument: conditions
• The condition filter applies OR logic to each value specified in the request.
  • The Decision API will return ad items that exactly match any of the condition values.

“condition”: {
    "conditions”: ["used", "refurbished", "new"]
}

delivery

Returns ad items matching the delivery_option field value.

• Delivery filtering uses 1 argument: delivery_option
• Delivery filtering does not use operators, you must specify a single value for delivery_option
  • The Decision API will return ad items that match the delivery_option value exactly.

“delivery”: {  
    “delivery_option”: “one-day”,  
}

gender

Returns ad items matching the values found in the gender field value.

• Gender filtering uses 1 argument: genders
• The filter applies OR logic to each value specified in the request.
  • The Decision API will return ad items that match the gender values exactly.

“gender”: {
    "genders”: ["male", "female", "unisex"]
}

location

Returns ad items matching the location field values.

• Each location value is multi-depth and may contain multiple location values. The exact depth of the location must be present in catalog item feed.
  • Example: To filter ad items based on the 2nd depth level of A>B>C category use
    A>B in the location filter
  • Example: US>CA>Redwoodcity;CA>SanFrancisco
    Filter: US>CA
• The location filter applies OR logic to each value specified in the request.
  • The Decision API will return ad items that match any of the locations within the list.

“location”: {  
    “locations”: [“A>B>C”, “X>Y>Z”],  
}

material

Returns ad items matching the material field values.

• Material filtering uses 1 argument: materials
• The filter applies OR logic to each value specified in the request.
  • The Decision API will return ad items that exactly match any of the given materials values.

“material”: {
    "materials”: ["rubber", "plastic", "metal"]
}

pattern

Returns ad items matching the pattern field values.

• Pattern filtering uses 1 argument: patterns
• The filter applies OR logic to each value specified in the request.
  • The Decision API will return ad items that exactly match any of the given patterns values.

“pattern”: {
    "patterns”: ["stripes", "solid", "floral"]
}

price

Returns ad items matching a price using the min_price and max_price values provided.

• Price filtering requires 2 arguments, min_price and max_price
• The Decision API returns ad items with a price within the specified range, including the min_price and max_price values. An item with a price of 1000 will be returned if the “min_price” = 1000, and “max_price” = 2000.

“price”: {  
    “min_price”: 1000.0,  
    “max_price”: 2000.0  
}

Using cutoff ranges:

Price x or more: Set “max_price” to be a large number that will cover the entire catalog of items:

“price”: {  
“min_price”: x,  
“max_price”: 1000000000000  
}

Price y or less: Set “min_price” to 0:

“price”: {  
	“min_price”: 0,  
	“max_price”: y  
}

Limitations

• min_price and max_price must be the same currency as the platform's default currency.

Invalid requests

The following conditions are considered invalid and will return a 400 BAD REQUEST error:

• “min_price” or “max_price” contains a negative number
• “min_price” is greater than “max_price”

rating

Returns ad items matching the rating field values.

• Rating filtering use 2 arguments: min and max
  • The Decision API returns ad items with ratings that are within the specified range, including the min and max values.

“rating”: {
    “min”: 4.0,
    “max”: 5.0
}

review_count

Returns ad items matching the review_count field values.

• Review_count filtering use 2 arguments: min and max
  • The Decision API returns ad items with ratings within the specified range, including the min and max values.

“rating”: {
    “min”: 4.0,
    “max”: 5.0
}

sale_price

Returns ad items matching a sale_price using the min_sale_price and max_sale_price values.

• Sale Price filtering uses two arguments, min_sale_price and max_sale_price.
• The Decision API returns ad items with a sale_price within the specified range, including the min_price and max_price values. An Item with a sale price of 1000 will be returned if the “min_sale_price” = 1000, and “max_sale_price” = 2000.

“sale_price”: {  
    “min_sale_price”: 1000.0,  
    “max_sale_price”: 2000.0  
}

Using cutoff ranges

Sale Price x or more: Set “max_sale_price” to number that will cover the entire catalog of items:

“sale_price”: {  
“min_sale_price”: x,  
“max_sale_price”: 1000000000000  
}

Sale Price y or less: Set “min_sale_price” to 0:

“sale_price”:{  
“min_sale_price”: 0,  
“max_sale_price”: y  
}

Limitations

• min_sale_price and max_sale_price must be the same currency as the platform's default currency and catalog.

Invalid requests

The following conditions are considered invalid and will return a 400 BAD REQUEST error:

• “min_sale_price” or “max_sale_price” contains a negative number
• “min_sale_price” is greater than “max_sale_price”

size

Returns ad items matching the size field values.

• Size filtering uses 1 argument: sizes
• The size filter applies OR logic to each value specified in the request.
  • The Decision API will return ad items that exactly match any of the given sizes.

“size”: {
    "sizes”: ["small", "medium", "large"]
}

FAQ

Q. What happens when all ad items are filtered out due to filtering criteria?

The decision API will return an empty response with a status code of 200 when:

• The filter combinations filter out all ad items.
• There are no active ad items that match the filtering criteria.