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 tags, 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.

Identifiers​

Carrot Ads requests bind a token, a retailer slug, and catalog identifiers to a banner. Use the values Instacart assigned for that banner and country.

X-Retailer-Id and retailer slugs​

X-Retailer-Id is the retailer slug for the banner that should serve ads. Instacart assigns slugs during onboarding. You cannot create or change slugs yourself.

The header is required only for multi-banner accounts. Single-banner accounts can omit it.

  • An unknown or missing slug returns 400 with the message Bad X-Retailer-Id.
  • A slug that does not match the OAuth token returns 401 with the message the given location code doesn't match the oauth token used.

US and Canada credentials​

US and Canada are separate OAuth applications. A token minted for one country is not valid for the other. Use the client ID, secret, retailer slug, and location codes that belong to that country.

RRC and UPC mapping​

Sponsored product and display item responses can include rrc, upc, or both, depending on how your catalog is configured:

  • rrc is the retailer reference code from your catalog inventory file. The field is omitted when your catalog is not configured with retailer reference codes.
  • upc is the universal product code in its original format, without normalization. The field is omitted when your catalog is not configured with UPCs.

When rrc or upc is absent, use product_id to resolve the item in your catalog. For catalog identifiers, see Item API request overview and Catalog.

Last updated on