Skip to main content

​
Filter Basics

The filter_group API parameter refines results by selecting only the products that match the given expressions and running the query on those products. The filter_group expects a filter expression. 
{
  "filter_group": {
    "conditional": "AND",
    "expressions": [
      {
        "property": "product_type",
        "operator": "eq",
        "values": ["Sweater"]
      },
      {
        "property": "options.color",
        "operator": "eq",
        "values": ["RED"]
      }
    ]
  }
}

​
Expressions and Operators

Expressions are the core of the filter language. 
{
  "property": "product_type",
  "operator": "eq",
  "values": ["Sweaters"]
}
  • property is the attribute of the field you want to filter on.
  • operator is the logical operator to apply (see full list below).
  • values is an array of values the operator compares against in the property.

​
Supported operators

OperatorDescription
eqEqual to a single value
neqNot equal to a single value
inMatches any value in the array
notInDoes not match any value in the array
gtGreater than
gteGreater than or equal to
ltLess than
lteLess than or equal to
betweenWithin a range (pass exactly two values)
notBetweenOutside a range (pass exactly two values)
containsString contains the given value
doesNotContainString does not contain the given value
beginsWithString starts with the given value
endsWithString ends with the given value
doesNotBeginWithString does not start with the given value
doesNotEndWithString does not end with the given value
nullValue is null or does not exist
notNullValue is not null (exists)

​
Examples of Basic Conditions

A condition to find products of type Sweaters: 
{
  "property": "product_type",
  "operator": "eq",
  "values": ["Sweaters"]
}
A condition to find products created after 1 January 2020 (UNIX Epoch time): 
{
  "property": "created_at",
  "operator": "gt",
  "values": [1577836800]
}
A condition to exclude gift card products: 
{
  "property": "is_gift_card",
  "operator": "eq",
  "values": [false]
}
A condition to find bundle products (products with variants that require components): 
{
  "property": "has_variants_that_require_components",
  "operator": "eq",
  "values": [true]
}
A condition to find products within a price range (e.g., between 10and10 and 50): 
{
  "property": "variants.price",
  "operator": "between",
  "values": [10, 50]
}
A condition to find products with variants available at specific location IDs (e.g., locations 1001 and 1002):
The variants.in_stock_location_ids field is no longer filterable. It is now a sort-only field used for location-based product demotion in sort orders. See Sorting for details on using this field in priority rules.
{
  "property": "variants.in_stock_location_ids",
  "operator": "in",
  "values": [1001, 1002]
}
A condition to find products whose title contains “organic”: 
{
  "property": "title",
  "operator": "contains",
  "values": ["organic"]
}
A condition to exclude products without a vendor (null check): 
{
  "property": "vendor",
  "operator": "notNull",
  "values": []
}
A condition to find products NOT in a price range (e.g., outside 10to10 to 50): 
{
  "property": "variants.price",
  "operator": "notBetween",
  "values": [10, 50]
}

​
Complex Filter Expressions

You can build advanced filter groups by combining expressions using AND and OR.

​
Example of Complex Expression

To include both Accessories and products from SUPREME published after 1 January 2020: 
{
  "conditional": "OR",
  "expressions": [
    {
      "conditional": "AND",
      "expressions": [
        {
          "property": "product_type",
          "operator": "eq",
          "values": ["Accessories"]
        },
        {
          "property": "vendor",
          "operator": "eq",
          "values": ["Supreme"]
        }
      ]
    },
    {
      "conditional": "AND",
      "expressions": [
        {
          "property": "published_at",
          "operator": "gt",
          "values": ["1577836800"]
        }
      ]
    }
  ]
}

​
Best practices

When crafting filter expressions:
  • Test complex expressions in a controlled environment before deployment.
  • Ensure consistent case usage for string attributes to prevent mismatches.
  • Use the between operator instead of combining gte and lte for range queries.
  • Nested filter groups support up to two levels of depth.

​
Troubleshooting

If your filter expression isn’t returning the expected results:
  • Verify that operator names use the exact camelCase format shown above (e.g., notIn, not not_in).
  • Confirm that attribute names and values match exactly with the data.
  • Ensure the values field is always an array, even for single-value operators like eq.
  • Check that the conditional field uses uppercase AND or OR.