Product Filtering Guide

Master advanced filtering techniques for precise product discovery. Learn price filters, attribute filtering, vendor filtering, and how to combine multiple filters effectively.

The Catalog API provides powerful filtering capabilities to help you find exactly the products you need. Learn how to combine different filter types for precise results and build sophisticated product discovery experiences.

What types of filters are available?

The Catalog API supports multiple filter types that can be combined for precise product discovery. All filters work with any search endpoint.

Price Filters

Filter products by price range using price_min and price_max:

Price Range

const response = await fetch('https://api.getcatalog.ai/api/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    query: 'dress',
    filters: {
      price_min: 50.00,
      price_max: 150.00
    }
  })
});

Prices are always in dollars. For example, $50.00.

Vendor Filters

Filter by specific vendors (brands):

Single Vendor

{
  "filters": {
    "vendor": "fwrd"
  }
}

Availability Filter

Filter by product availability:

Available Only

{
  "filters": {
    "is_available": true
  }
}

Attribute Filters

Use the attributes object to filter by rich product properties:

Color Filtering

Single Color

{
  "filters": {
    "attributes": {
      "color": "blue"
    }
  }
}

Material and Fabric

Material Filter

{
  "filters": {
    "attributes": {
      "material": "silk"
    }
  }
}

Demographic Filters

Gender Filter

{
  "filters": {
    "attributes": {
      "gender": "women"
    }
  }
}

Category Filtering

Filter by product categories using hierarchical paths:

Category Filter

{
  "filters": {
    "attributes": {
      "category": "Women > Dresses"
    }
  }
}

How do you combine multiple filters?

Combine multiple filters for precise results. All filters use AND logic:

Complex Filter Example

{
  "query": "summer party dress",
  "filters": {
    "price_max": 200.00,
    "vendor": ["fwrd", "Ganni"],
    "is_available": true,
    "attributes": {
      "gender": "women",
      "season": "summer",
      "occasion": ["party", "formal"],
      "color": ["blue", "pink", "white"],
      "material": "silk"
    }
  }
}

How does filter logic work?

AND vs OR Logic

• Between filter types: AND logic (product must match ALL specified filters)
• Within arrays: OR logic (product must match ANY value in the array)

Filter Logic Example

{
  "filters": {
    "price_max": 150.00,        // AND price <= $150
    "vendor": ["fwrd", "Ganni"],  // AND vendor is fwrd OR Ganni
    "attributes": {
      "color": ["blue", "red"],      // AND color is blue OR red
      "season": "summer"             // AND season is summer
    }
  }
}

This finds products that are:

• Under $150 AND
• From fwrd OR Ganni AND
• Blue OR red AND
• For summer

What are the filtering best practices?

Start Broad, Then Narrow

Begin with broad filters and progressively add more specific criteria:

Step 1: Basic Filter

{
  "query": "dress",
  "filters": {
    "is_available": true
  }
}

Use Semantic Search + Filters

Combine natural language queries with precise filters:

Semantic + Filters

{
  "query": "elegant minimalist work outfit",
  "filters": {
    "attributes": {
      "occasion": "work",
      "color": ["black", "navy", "grey"],
      "gender": "women"
    }
  }
}

Handle Empty Results

Always handle cases where filters return no results:

Error Handling

const searchWithFallback = async (query, filters) => {
  // Try with all filters
  let response = await search(query, filters);
  
  if (response.products.length === 0) {
    // Remove some specific filters and retry
    const relaxedFilters = { ...filters };
    delete relaxedFilters.attributes?.color;
    
    response = await search(query, relaxedFilters);
  }
  
  if (response.products.length === 0) {
    // Further fallback: just the query
    response = await search(query, {});
  }
  
  return response;
};

What are common filtering patterns for different use cases?

Sustainable Fashion

Sustainable Products

{
  "query": "sustainable eco-friendly",
  "filters": {
    "attributes": {
      "fabric": ["organic cotton", "linen", "hemp"],
      "material": ["cotton", "linen", "hemp"]
    }
  }
}

Luxury Items

Luxury Filter

{
  "query": "luxury designer",
  "filters": {
    "price_min": 500.00,
    "vendor": ["Chanel", "Gucci", "Prada"]
  }
}

Seasonal Shopping

Summer Collection

{
  "query": "summer collection",
  "filters": {
    "attributes": {
      "season": "summer",
      "color": ["white", "blue", "yellow", "pink"]
    }
  }
}

Occasion-Based

Wedding Guest

{
  "query": "wedding guest dress",
  "filters": {
    "attributes": {
      "occasion": "formal",
      "color": ["blue", "pink", "green", "yellow"]  // Avoid white
    }
  }
}

How do you optimize filtering performance?

• Use specific vendor filters when possible for faster results
• Combine semantic queries with filters for better relevance
• Start with broader filters and progressively narrow down
• Cache common filter combinations for better user experience

The API is optimized for real-time filtering with sub-100ms response times. All attributes are indexed for fast filtering performance.

Related resources

• Quickstart Guide - Learn basic filtering with your first API request
• API Reference - Complete parameter documentation for all endpoints
• Pagination Guide - Handle large filtered result sets effectively