Skip to main content
POST
/
{collection_handle}
/
facets
Facets API: Get Collection Facets
curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/{collection_handle}/facets \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "filter_group": {}
}
'
POST /storefront/v1/summer-collection/facets

{
  "facets": ["vendor", "product_type", "price_range"],
  "retrieveFacetCount": true,
  "includeFacetRanges": true
}

​
Authorization

​
X-Storefront-Access-Token
string
required
Token-based authentication header in the form of <YOUR_LAYERS_TOKEN>.

​
Headers

​
Content-Type
string
default:"application/json"
required
​
Accept
string
default:"application/json"
required

​
Path parameters

​
collection_handle
string
required
The handle of the collection to retrieve facets for.

​
Body

​
facets
string[]
Facets to be included. Accepts both exact facet codes (e.g., "vendor", "options.Size") and wildcard patterns (e.g., "options.*", "metafields.product.*").Wildcard patterns expand to all matching attribute codes. For example, "options.*" expands to all option facets like "options.Size" and "options.Color". Wildcards must match at least one attribute code to be valid.Examples:
// Exact facet codes
"facets": ["vendor", "options.Size", "options.Color"]

// Wildcard pattern
"facets": ["options.*"]

// Mixed exact and wildcard
"facets": ["vendor", "options.*", "metafields.product.*"]
​
retrieveFacetCount
boolean
If the count of each facet value should be calculated
​
includeFacetRanges
boolean
If you want a min/max range for numeric facets such as price.
​
filter_group
object
Refer to our dedicated Filter Expressions guide to learn more about filter expressions.

​
Response

This endpoint returns facet metadata only — it does not return product results, pagination fields, or an attributionToken. If you need products alongside facets, use the Browse API with retrieveFacetCount enabled instead.
​
facets
object
Object whose keys are facet attribute codes and whose values are objects mapping each facet value to its result count. Only returned when retrieveFacetCount is true.
​
facetRanges
object
Object whose keys are facet attribute codes and whose values are objects with min and max numeric properties. Only returned when includeFacetRanges is true.
​
filters
object
Echo of the filter group expressions that were applied when computing the counts. Useful for verifying that the request’s filter_group was interpreted as expected.

​
When to use

Use this endpoint when you need facet data without fetching product results. Common scenarios include:
  • Pre-loading filter options: Fetch available filter values before the user starts browsing
  • Sidebar filters: Build filter UIs that show available options and counts independently of the product grid
  • Reducing payload size: Avoid fetching full product data when you only need facet information
For combined product results and facets in a single request, use the Browse API with retrieveFacetCount enabled instead. 
POST /storefront/v1/summer-collection/facets

{
  "facets": ["vendor", "product_type", "price_range"],
  "retrieveFacetCount": true,
  "includeFacetRanges": true
}