Skip to main content
POST /products/facet-counts counts the products that POST /products/search would filter to. Use it to build filter menus and category navigation that show how many products each option would return, and to hide options that return nothing. Send the same filters you would send to search: q, facets, exclude_facets, price and brand-quality bounds, and catalogs. Then say what to count:
  • categories: one count per category you name, such as the children from GET /taxonomy/categories.
  • attributes or derive_attributes: counts per value of enrichment attributes, such as neckline or fabric.
  • facet_names: counts per value of color_family or category_path.depth_0.
Counts span every catalog your key can access unless catalogs narrows them, exactly as search does. Unlike the taxonomy endpoints, which return definitions, these counts reflect indexed products in your scope. This endpoint is not billed. It is rate limited like every /v1 route.

Request

Filter parameters

These fields mean exactly what they mean on POST /products/search, and follow the same validation rules. Every field is optional. Unknown fields return a 422.
string
Free-text query, up to 1,000 characters, understood as search understands it. The category, gender, color, brand, price, and attribute filters understood from q apply to the counts. The text itself does not narrow them. A blank string is the same as omitting it.
Facet[]
Filters a product must match, as on search. A facet you send replaces any understood facet of the same name. Each name may appear at most once; at most 50 entries. See Facet names.
Facet[]
Filters a product must not match, as on search. At most 50 entries.
string[]
Understood facets to drop, as on search. Requires q.
string[]
Category path, root first, with 1–4 category names, to filter to when understanding finds no category in q. Requires q.
number
Inclusive minimum price, at least 0.
number
Inclusive maximum price, at least 0.
number
Inclusive minimum brand quality score, from 1 to 6.
number
Inclusive maximum brand quality score, from 1 to 6.
string[]
1 to 500 catalog keys to count in. Omit it to count every catalog your key can access. Keys your key cannot access count nothing.

Count parameters

Send at least one of categories, attributes, derive_attributes, or facet_names. Because facet_names defaults to ["color_family"], a request with none of them counts color families.
FacetCountCategory[]
Up to 100 categories to count. Each count is the products matching the filters above and the category’s own facets. Each entry has:
  • key (string, 1–200 characters, required): your identifier for the category. Its count carries it back. Keys must be unique.
  • facets (Facet[], 1–10 entries, required): the facets that select the category, such as a GET /taxonomy/categories entry’s facets. Each name at most once.
Facet[]
Filters that apply to attribute and facet_names counts only, such as the category being browsed. Category counts ignore them, so sibling categories keep their own counts. Each name may appear at most once; at most 50 entries.
string[]
Up to 50 attribute handles, such as neckline, whose values to count. Find a category’s handles with GET /taxonomy/attributes. Each handle must be filterable and may appear once. A value’s count ignores your own facet on that attribute, so every value shows what selecting it would return.
boolean
default:"false"
Count every filterable attribute on any leaf category under the category path in context_facets (its category_path.depth_N facets), instead of naming attributes. Attributes that apply to more leaf categories come first. With no category path in context_facets, no attributes are counted. Cannot be combined with attributes.
string[]
default:"[\"color_family\"]"
Up to 2 facets whose values to count: color_family and category_path.depth_0 (top-level categories). Like attributes, a count ignores your own facet of that name. Send [] to skip them.
integer
default:"100"
Most values returned per attribute and per facet, highest counts first. From 1 to 1,000.

Example

Count the children of Clothing for women under $200, and the neckline and color-family values within Dresses:

Response

CategoryCount[]
required
One entry per requested category, in request order. Each has key (the key you sent) and count.
AttributeCounts[]
required
One entry per counted attribute, in request order, or in derived order with derive_attributes.
FacetValueCounts[]
required
One entry per name in facet_names, in request order. Each has name and values, with values as above.
object
required
The filters and bounds the counts applied, with each facet’s origin, as search reports them. See Effective query.

Example response

Errors

See the overview for authentication and rate-limit errors. Operation ID: countProductFacets. SDK methods: Python count_product_facets(...); TypeScript countProductFacets({ ... }). The SDKs take the same fields, in camelCase for TypeScript. The MCP server has no equivalent tool.