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. When the metaobject defines a color or image field, the entry also carries a resolved swatch object.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
Storefront endpoints accept nested AND/OR filter groups up to two levels deep. Each nested group must contain at least one expression; empty nested groups are rejected. Metafield filter properties may include hyphens in their namespace or key, for example metafields.my-app.fit-type.Refer to the 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.Fixed amounts use your shop’s base currency. Layers skips them on market pricing rows in a different native currency, without converting the discount. Percentage discounts still apply to those localized prices. A variant that falls back to its base price can still receive a fixed-amount discount.

​
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
Returned when at least one requested facet has display data to hydrate. Omitted when empty.Keys are facet attribute codes. Values are objects that map each facet value to a display object:
  • For facets backed by a metaobject_reference or list.metaobject_reference metafield, each entry maps the referenced metaobject’s handle to its display_name and fields. These entries require enrichFacetMetaobjects: true and are hydrated from the local metaobject cache. Handles with no cached metaobject are omitted from facetDisplay and remain as plain values under facets. See Metaobjects and reference metafields for the normalized field shape.
  • Metaobject entries also carry a swatch object when the metaobject defines a color or image field. The swatch is ready to render as an image thumbnail or color chip:
    • { "type": "image", "url": "…", "alt": "…" } when the metaobject has a file_reference or list.file_reference field that points at an image. alt is present only when the image has alt text. Videos and documents in the field are skipped; the swatch comes from the field’s first image.
    • { "type": "color", "colors": ["#191970"] } when the metaobject has a color or list.color field instead. colors lists every hex value on the field, so a two-tone value carries two entries.
    An image swatch wins over a color swatch when the metaobject defines both field types. Among fields of the same kind, the field order on the metaobject definition decides. The swatch key is absent when the metaobject has no color or image field.
  • For variants.pickup_locations, each entry maps a Shopify location id to the location’s id, name, address, instructions, pickupTime, and (when the filter is a geoRadius) distance and distanceUnit. These entries are returned whenever pickup facets are requested, regardless of enrichFacetMetaobjects. See Local pickup filtering for the full 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 shopper 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.