How to specify preferred brands

If you want to promote one or more brands within a recipe or shopping list, you can add brand filters to some or all of the items in your requests. When a customer navigates to the recipe page or shopping list page, these brands are shown in the list of matching products. If a brand match is not found at the store, a link to a list of possible alternatives is provided.

You can specify preferred brands by making an API request with the Filter object set on some or all of the items. There is no limit to the number of brands that can be added to a filters array, however for best results, we recommend 10 or fewer brands per item.

The Filter object consists of the following arrays:

brand_filters: An optional filter that returns only products of the brand names specified in the API request.
health_filters: An optional filter that returns only health specific products specified in the API request.

Add the brand names to the brand_filters array separated by commas. The brand filter is case-sensitive. Brand names must be spelled exactly as they appear in the catalog.

By keeping the brand names separate from the product names, Instacart can match other similar products by any of the brand names in the array.

The following code sample shows how to update a few of the ingredients from the request that we created in the Create a recipe page tutorial to include brand filters:

[
  {
    "name": "whole milk",
    "quantity": 0.5,
    "unit": "cup",
    "filters": {
      "brand_filters": ["Lucerne", "Clover"]
    }
  },
  {
    "name": "egg",
    "quantity": 1,
    "unit": "large",
    "filters": {
      "brand_filters": ["Kirkland"]
    }
  },
  {
    "name": "ground cinnamon",
    "quantity": 0.25,
    "unit": "teaspoon",
    "filters": {
      "brand_filters": ["McCormick®"]
    }
  }
]

Try it out

To try this out yourself, copy this sample request and substitute in your API key. Click the link in the response to confirm that the brands can be seen in the recipe page.

The following image shows a recipe page containing the brands specified in the API request:

Add brand filters​

Try it out​

Add brand filters

Try it out