Skip to main content
POST
Text Search: Execute Search

​
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
​
string
Optional header to identify SDK client requests. Format: sdk-name/version (e.g., layers-js-sdk/1.0.0). When provided with version >= 1.0.0, the server returns HTTP 425 (Too Early) with a Retry-After header when prepared search data isn’t ready yet, instead of blocking, so the client can poll until the search is ready.

​
Path parameters

​
string
required
The url-encoded search query. Layers normalizes the query before validating it, stripping invisible characters and converting Unicode punctuation to ASCII equivalents. After normalization, the query must be 2 to 255 characters. Queries outside this range return HTTP 422.

​
Body

​
string[]
Product attributes to include in the response. By default, all attributes are included except opt-in attributes noted below. Available attributes include: id, title, handle, body_html, vendor, product_type, tags, images, available, created_at, updated_at, published_at, price_range, options, original_options, metafields, named_tags, calculated, category, featured_media, is_gift_card, has_variants_that_require_components, combined_listing_parent_product_id, combined_listing_role, first_or_matched_variant, and variants. The collection_titles attribute is opt-in: pass it in attributes to include the array of collection titles each product belongs to. It is excluded from responses by default. See the Product Schema for detailed descriptions, including nested field selection for slicing arrays and filtering collections (for example, images[:2].src, variants[sku=ABC].price, metafields[namespace=custom]).
​
string
ULID identifier from the Prepare Search endpoint for optimized search execution. When provided, reuses the precomputed intent analysis and query expansions from that prepare call so the search returns faster.
​
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.
​
Pagination Object
​
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.
​
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.
​
array
Specify which product variants should be selected by default in the first_or_matched_variant field. This is a presentation preference for search and browse results, not a product filter. Request transforms can set or replace this complete list with the set_default_selected_options action.Behavior:
  • Uses OR logic - selects the first variant matching ANY of the specified option values
  • Query and keyword matches, plus pinned variant choices, take priority over these defaults
  • Configured defaults take priority over a confident semantic match to a variant
  • If no variant matches the configured defaults, a confident semantic match can still be selected before falling back to the first variant by position
  • Automatically skipped when any option or variant filters are applied (filters take precedence)
  • Only affects the first_or_matched_variant field in the response
  • Works with Variant Breakouts: product tiles respect default selected options, and variant tiles respect non-breakout default selected options, preferring matching variants within each breakout group and falling back to position when needed. This does not change breakout grouping or collapse breakout tiles.
Example:
Multiple options example (OR logic):
This selects variants with either February OR March birthstone, preferring the first match found.
​
object
User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.
​
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.
​
string
Code of the sort order to apply. Use "relevance" for the default relevance-based ranking, or any custom sort order code configured in your store. Retrieve available sort order codes from the Sort Orders API.
​
boolean
default:"false"
When set to true, products with no available variants are excluded from results regardless of the store-level out-of-stock visibility setting. If your store’s inventory location scope is narrowed, the same location rules apply.This is useful when a specific search integration or page requires strict in-stock filtering even though the store default allows out-of-stock products to appear.
​
object
Per-request overrides for response behavior. Currently controls image preload hints emitted in the Link response header. You can disable preloads or narrow the srcset to the breakpoints your storefront uses. You cannot enable preloads when the store has them disabled.Example:

​
Why result totals can differ

totalResults is computed for each request. It is the number of products that clear Layers’ relevance thresholds for that request’s query interpretation and filters. Two requests for the same text can return different totals when:
  • They use different prepare calls. Each search_id carries its own query expansions and intent analysis. To avoid generating intent rules for every keystroke, Layers only generates a new intent modifier (for example, a “jeans” category preference) once it has seen the same query text before, or once the query belongs to a known query cluster. An instant-results request fired while the shopper is still typing is often the first time Layers sees that text, so it can be interpreted more broadly or more narrowly than the results-page search that follows.
  • They use different filters. filter_group values, system filters, and variant breakouts all change what is counted.
  • The catalog or query data changed between the calls. Examples are a catalog sync, a newly learned query cluster, or an updated merchandising rule.
Relevance thresholds are relative to the best match for each request. Any difference in how the query is interpreted therefore changes how many products are counted, not just their order. Which count to show: use totalResults from the results-page search request, meaning the request that renders the grid with the shopper’s filters. Treat totals from instant-results or preview requests (small limit, no facets) as approximate. If you show a “View all N results” link in a typeahead, either leave out the number or take it from the same search_id the results page will use.
The Autocomplete endpoint returns query suggestions only and has no product count. A count shown next to typeahead products always comes from a separate Search request.

​
Response

​
Array of Objects
Semantic Redirects: When a text search query semantically matches a configured redirect term, the response will include a _meta.redirect object with the redirect URL. In this case, the results array will be empty and totalResults will be 0. Semantic redirects only apply to text search queries (not image or similar product searches).
Degraded responses: Optional relevance steps such as query expansion, intent modifiers, and personalization boosts fail open. If one of these steps is temporarily unavailable, Layers skips it and returns HTTP 200 with results instead of an error. Skipped steps do not appear in _workflow. If Layers is temporarily serving keyword-only results platform-wide, the response includes _meta.search_lane set to "prefix_only".
​
number
The total number of results that passed relevance filtering for this request, across all pages. It does not depend on pagination.limit, pagination.page, or which facets you request. When variant breakouts are enabled, this reflects the count of tiles (both product and variant tiles) rather than just products. See Why result totals can differ.
​
number
The current page number.
​
number
The total number of pages. Calculated based on tile count when variant breakouts are enabled.
​
string
A unique request identifier (ULID) for this API call. Use this token to correlate search requests with analytics events via the Beacon API, and to match requests to entries in the Search Inspector.
​
object
If includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.
​
object
If retrieveFacetCount is true then an object with keys and values of the specified attributes. When variant breakouts are enabled, facet counts reflect tile counts rather than product counts. Empty values and literal "null" strings are automatically excluded from facet results.
​
object
Returned when at least one requested facet has display data to hydrate. Keys are facet attribute codes; values map each facet value to a display object.Metaobject-reference facets require enrichFacetMetaobjects: true and map each handle to the metaobject’s display_name and fields. Entries also carry a swatch object when the metaobject defines a color or image field. Handles with no matching cached metaobject are omitted here and remain as plain values in facets. See Metaobjects and reference metafields for the normalized field shape and the Facets API response for the swatch shape.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. Pickup entries are returned whenever pickup facets are requested, regardless of enrichFacetMetaobjects. See Local pickup filtering.
​
object
​
array of objects
An ordered trace of processing steps the engine performed to produce results for this request. Each entry represents a stage in the search pipeline, recorded in the order it was executed. Use this field to understand how Layers interpreted and transformed your query, which rules and boosts were applied, and why results appear in a particular order.This field is useful for debugging search behavior in development and is also surfaced in the Search Inspector panel.

​
Response headers

Every API response includes the following headers for request tracing and performance optimization:

​
Variant breakouts

When variant breakouts are configured, results may include both product tiles and variant tiles. Each result includes a __typename field to identify the tile type:
​
string
Identifies the type of tile in the results:
  • "Product" - A standard product tile
  • "Variant" - An individual variant tile from a product with a configured breakout option

​
Variant tile fields

Variant tiles include additional fields to identify the specific variant:
​
number
The parent product ID. Use this to link back to the full product or group variants from the same product.
​
number
The specific variant ID. For variant tiles, this matches the id field.
For variant tiles, the id field contains the variant ID (not the product ID). The title field is formatted as "{product title} - {option value}" by default (e.g., “Amethyst Ring - Rose Quartz”), but the format can be configured per breakout. If the breakout’s Include Option Value in Title setting is disabled, the title is the original product title. See the Variant Breakouts documentation for more details.