Skip to main content

Filters and catalog identifiers

To use the FilterQuery object in Carrot Ads requests, the products in your catalog inventory file must include the identifiers that you plan to use to filter the ads. You'll need to ensure that the catalog file contains the necessary columns and values for the products you want to target. For help with setting up your catalog to support filters, contact your Instacart representative.

You can create filters for the following:

  • Custom product attributes, such as gluten free or vegetarian
  • Product categories, such as produce or snacks
  • Brands

For more information about special integration requirements in the catalog inventory file specification, see Special integration requirements.

Custom product tags​

To filter ads by custom product tags, like dye_free or vegan, add the tags to the catalog inventory file. Create a column called carrot_ads_product_tags, and add custom tags for each product as a comma separated list of strings. Tags values are alphanumeric and must use underscores instead of spaces.

Column name: carrot_ads_product_tags

Data type: CSV/string

Example: dairy_free, dye_free, vegan, raw

When you retrieve ads, you can limit the returned ads to products that match the filters you specify in your request.

Product categories​

To filter ads by product categories, like departments and aisles, add the categories and subcategories to the catalog inventory file. Create a column called retailer_specific_metadata and list the categories with their unique identifiers using JSON syntax.

In the JSON, the first line is the highest level category the product belongs to and you can add subcategory levels nested within the hierarchy. The IDs must be unique across categories, that is, you can't have multiple categories or subcategories with the same ID. The catalog hierarchy can be as shallow or deep as you need for any product. Products can belong to more than one category. When necessary, you can also specify custom category IDs that don't need to be part of a category hierarchy.

Column name: retailer_specific_metadata

Data type: JSON

Example:

{
  "product_category_l1_id": [1],
  "product_category_l2_id": [11],
  "product_category_l3_id": [111],
  "product_category_l4_id": [1111, 2222],
  "product_category_l5_id": [11111, 22222],
  "product_category_l6_id": [111111],
  "product_category_custom_id": [100, 200]
}

When you retrieve ads, you can limit the returned ads to products that match the filters you specify. Products that belong to the specified ID are included.

Brands​

To filter ads by brand, add the brand ID to the catalog inventory file. In the retailer_specific_metadata column, list the unique brand identifiers using JSON syntax.

Column name: retailer_specific_metadata

Data type: JSON/integer

Example:

{
  "brand_id": 123
}

When you retrieve ads, you can limit the returned ads to products that match the brands you specify.

Last updated on