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 fromGET /taxonomy/categories.attributesorderive_attributes: counts per value of enrichment attributes, such asnecklineorfabric.facet_names: counts per value ofcolor_familyorcategory_path.depth_0.
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 onPOST /products/search, and follow the same validation rules. Every field is optional. Unknown fields return a 422.
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.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.
Category path, root first, with 1–4 category names, to filter to when understanding finds no category in
q. Requires q.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 ofcategories, attributes, derive_attributes, or facet_names. Because facet_names defaults to ["color_family"], a request with none of them counts color families.
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 aGET /taxonomy/categoriesentry’sfacets. Each name at most once.
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.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.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.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.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
One entry per requested category, in request order. Each has
key (the key you sent) and count.One entry per counted attribute, in request order, or in derived order with
derive_attributes.One entry per name in
facet_names, in request order. Each has name and values, with values as above.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.