Skip to main content
POST
Facets API: Get Collection Facets

​
Authorization

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

​
Headers

​
string
default:"application/json"
required
​
string
default:"application/json"
required

​
Path parameters

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

​
Body

​
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:
​
boolean
If the count of each facet value should be calculated.
​
boolean
If you want a min/max range for numeric facets such as price.
​
boolean
When true, any facet backed by a metaobject_reference or list.metaobject_reference metafield is returned with a companion facetDisplay object. Each entry maps a facet value (the metaobject handle) to the referenced metaobject’s display_name and fields.Use this when your storefront filter UI needs human-readable labels or nested field data (for example, a color name or swatch hex) instead of the raw handle. When false or omitted, only the handles are returned in facets.Values are looked up from the local metaobject cache. Handles with no matching cached metaobject are omitted from facetDisplay and remain as plain values in facets. See Metaobjects and reference metafields for the normalized shape of each entry.
​
object
Refer to our dedicated Filter Expressions guide to learn more about filter expressions.
​
object
Contextual information about the customer’s session, behavior, and environment. Automatically collected by the Storefront Pixel; must be manually provided for headless integrations. See Contextual Information for implementation guidance.
​
array
Apply discounts to products, variants, or collections. When provided, price-based sorting and filtering will use discounted prices. See the Discount Entitlements guide for detailed usage.

​
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.
​
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.Counts are scoped to the visibility of the active shopping channel, so they always match the number of products a shopper can actually see in the collection for that channel. Products that are not published to the requester’s channel, are B2B-only, or are hidden by a combined-listing role are excluded from every bucket. When the request is a mobile app request but the store does not have an app sales channel configured, counts fall back to the web channel.When filter_group is present, counts follow the standard “OR within a facet, AND across facets” pattern. Facets whose condition uses a multi-select operator (IN, NOT IN) are counted against every other active filter except the facet’s own condition, so other values in the same facet stay selectable. Facets whose condition uses a single-select or predicate operator (EQ, NEQ, GT, LT, BETWEEN, NULL, and so on) are counted against the fully filtered result set. Facets without an active condition are always counted against the full filter group.
​
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.Ranges are computed only over products visible on the active shopping channel. A numeric range — for example, a price slider’s min and max — cannot come from a product the shopper cannot see.variants.price and variants.compare_at_price counts and ranges are always converted to the resolved market’s currency. A price slider’s min and max match the prices a shopper actually sees for their market. The market is resolved from context.market when provided, or from context.geo.country otherwise, and falls back to the store’s primary market. This matches the pricing behavior of the Browse API with retrieveFacetCount enabled. Both endpoints return consistent counts and ranges for the same filter group.When the request also includes discountEntitlements, discounts are applied on top of the market-converted price. See Discount entitlements for details.
​
object
Only returned when enrichFacetMetaobjects is true and at least one requested facet is backed by a metaobject_reference or list.metaobject_reference metafield.Keys are facet attribute codes. Values are objects that map each facet value (the referenced metaobject’s handle) to the metaobject’s display_name and fields. Facet values whose handle is not found in the local metaobject cache are omitted from facetDisplay and remain as plain handles under facets. Use this to render human-readable labels or swatch data next to filter checkboxes without a second lookup. See Metaobjects and reference metafields for the normalized field shape.
​
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.