Text Search: Execute Search

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

string

default:"application/json"

required

X-SDK-Client

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. This enables efficient client-side polling for async search operations.

Path parameters

searchQuery

string

required

The url-encoded search query.

Body

attributes

string[]

Product attributes to include in the response. By default, all attributes are included. 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. See the Product Schema for detailed descriptions.

search_id

string

ULID identifier from the Prepare Search endpoint for optimized search execution. When provided, uses pre-computed embeddings and query expansions.

filter_group

object

Refer to our dedicated Filter Expressions guide to learn more about filter expressions.

pagination

Pagination Object

Show pagination

page

int

The current page of results to fetch.

limit

int

The max results to fetch per page

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.

discountEntitlements

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.

Show Discount Entitlement Object

entitled

object

required

Defines which products qualify for the discount.

Show entitled

all

boolean

When true, applies discount to all products. When false, uses products, variants, or collections arrays.

products

string[]

Array of product IDs or handles that qualify for the discount.

variants

string[] | number[]

Array of variant IDs that qualify for the discount.

collections

string[]

Array of collection handles that qualify for the discount.

discount

object

required

Defines the discount to apply.

Show discount

type

string

required

The discount type: PERCENTAGE or FIXED_AMOUNT.

value

number

required

The discount value. For PERCENTAGE, this must be a number between 0 and 100 (e.g., 10 for 10% off). For FIXED_AMOUNT, this is the currency amount.

defaultSelectedOptions

array

Specify which product variants should be selected by default in the first_or_matched_variant field. This is useful for scenarios like defaulting to a specific birthstone option when searching in a jewelry store.

Show Properties

optionCode

string

required

The product option code to match (e.g., "birthstone", "color"). Option codes are automatically normalized (e.g., "Birth Stone" becomes "birth_stone").

value

string

required

The option value to match (e.g., "February", "Blue").

Behavior:

Uses OR logic - selects the first variant matching ANY of the specified option values
Falls back to the first variant by position if no match is found
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 your default selected options, and variant tiles respect non-breakout default selected options (preferring variants that match your preferences within each breakout group, with fallback to position ordering)

Example:

{
  "defaultSelectedOptions": [
    {
      "optionCode": "birthstone",
      "value": "February"
    }
  ]
}

Multiple options example (OR logic):

{
  "defaultSelectedOptions": [
    {
      "optionCode": "birthstone",
      "value": "February"
    },
    {
      "optionCode": "birthstone",
      "value": "March"
    }
  ]
}

This will select variants with either February OR March birthstone, preferring the first match found.

identity

object

User identity information for tracking and personalization. Automatically managed by the Storefront Pixel; required for headless integrations.

Show Properties

deviceId

string

Persistent browser identifier that remains constant across sessions. Used to recognize returning visitors for long-term personalization. Automatically generated and managed by the Storefront Pixel.

sessionId

string

Temporary session identifier. Typically corresponds to the Shopify session ID and expires after inactivity or when the browser is closed.

customerId

string

Shopify customer ID for authenticated users. Only present when the user is signed in to their account.

context

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.

Show Properties

geo

object

Geographic location information for regional personalization and merchandising. Automatically determined by the platform for client-side requests based on IP address. For server-side API calls (headless integrations), you should provide this explicitly.

Show Properties

country

string

Country code or name (e.g., “US”, “Canada”).

province

string

State or province name (e.g., “California”, “Ontario”).

city

string

City name (e.g., “Los Angeles”, “Toronto”).

productsInCart

array

Products currently in the customer’s cart. Used to surface complementary products and influence relevance scoring.

Show Array Item Properties

title

string

required

Product title.

price

number

Product price.

type

string

Product type or category.

productId

string

Product identifier. Accepts a numeric ID (e.g., "8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").

variantId

string

Product variant identifier.

options

object

Product variant options (e.g., {"Size": "11", "Color": "Red"}).

productsPurchased

array

Products the customer has previously purchased. Informs recommendations and prevents over-promotion of owned items.

Show Array Item Properties

title

string

required

Product title.

price

number

Product price at time of purchase.

type

string

Product type or category.

productId

string

Product identifier. Accepts a numeric ID (e.g., "8234567890123") or a Shopify GID (e.g., "gid://shopify/Product/8234567890123").

variantId

string

Product variant identifier.

options

object

Product variant options (e.g., {"Size": "11", "Color": "Red"}).

priorSearches

array

Recent search queries and their outcomes. Helps understand customer intent and refine relevance models.

Show Array Item Properties

searchQuery

string

required

The search query text.

hadClick

boolean

required

Whether the customer clicked on any results from this search.

hasResults

boolean

required

Whether the search returned any results.

fromPage

string

The page the search was initiated from (e.g., the referring page URL or page type).

marketing

object

UTM parameters and marketing campaign information for attribution tracking.

Show Properties

source

string

Marketing source (e.g., “google”, “facebook”).

medium

string

Marketing medium (e.g., “cpc”, “email”, “social”).

campaign

string

Campaign name.

term

string

Search term or keyword.

customer

object

Aggregated customer behavior and purchase patterns for personalization.

Show Properties

signedIn

boolean

Whether the customer is currently authenticated.

returning

boolean

Whether this is a returning customer.

numberOfOrders

integer

Total number of orders placed.

averageOrderValue

number

Average order value in store currency.

daysBetweenOrders

integer

Average days between orders.

daysSinceLastOrder

integer

Days since the most recent order.

daysSinceOldestOrder

integer

Days since the first order.

totalSpent

number

Total amount spent in store currency.

shoppingChannel

string

default:"web"

The shopping channel the customer is browsing from. Used for channel-specific merchandising, sorting, and analytics segmentation. Automatically detected from request headers when not provided (e.g., mobile app requests via Tapcart or Canvas are detected as "app").Accepted values:

"web" — Standard web browser (default)
"app" — Mobile app (e.g., Tapcart, Canvas)

custom

object

Custom contextual data specific to your implementation. Structure is flexible and can contain any key-value pairs relevant to your use case.

sort_order_code

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.

forceHideOutOfStock

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 has location-based stock checking configured, 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.

Response

results

Array of Objects

Show Properties

number

The unique identifier of the product.

title

string

The title of the product.

body_html

string

The HTML content describing the product.

vendor

string

The vendor of the product.

product_type

string

The type of the product.

created_at

number

The timestamp when the product was created.

handle

string

The handle of the product.

updated_at

number

The timestamp when the product was updated.

published_at

number

The timestamp when the product was published.

category

Object

The Shopify Product Taxonomy Category of the product.

Show Properties

name

string

The name of the category leaf.

full_name

string

The full name of the category.

string

The ID of the category.

is_leaf

boolean

Is the category a root category.

is_root

boolean

Is the category a root category.

first_or_matched_variant

Object

The first available variant (depending on OOS settings) or the variant matched with a filter or search query.

Show Properties

number

The ID of the variant.

title

string

The title of the variant.

available

boolean

The availability of the variant.

sku

number

The sku of the variant.

price

string

The price of the variant.

compare_at_price

string

The compare at price of the variant.

metafields

Object

The metafields of the variant.

selected_options

Array of Objects

The selected options of the variant.

Show Properties

name

string

The name of the option.

value

string

The value of the option

option_value

object

The linked metafield of the option.

position

number

The position of the variant in the product’s variant list.

inventory_quantity

number

Total inventory quantity across all locations. Only included when the store has the Expose Variant Inventory setting enabled.

inventory_policy

string

Inventory policy for the variant: DENY (stop selling when out of stock) or CONTINUE (allow overselling). Only included when the store has the Expose Variant Inventory setting enabled.

inventory_levels

object

Object mapping location IDs to available inventory quantities (e.g., {"1001": 5, "1002": 10}). Returns empty object {} when no inventory data exists. Only included when the store has the Expose Variant Inventory setting enabled.

featured_media

Object

The featured media of the product.

Show Properties

mediaContentType

string

The type of media.

alt

string

The alt text of the image.

src

string

The src of the image.

width

number

The width of the image.

height

number

The height of the image.

featured_media

Object

The featured media of the product.

Show Properties

mediaContentType

string

The type of media.

alt

string

The alt text of the image.

src

string

The src of the image.

width

number

The width of the image.

height

number

The height of the image.

available

boolean

The availability of the product.

price_range

Object

The price range of the product.

Show Properties

from

number

The starting price of the product.

number

The ending price of the product.

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).

totalResults

number

The total number of results. When variant breakouts are enabled, this reflects the count of tiles (both product and variant tiles) rather than just products.

page

number

The current page number.

totalPages

number

The total number of pages. Calculated based on tile count when variant breakouts are enabled.

attributionToken

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.

facetRanges

object

If includeFacetRanges is true then an object with keys of the facet attribute code and value is an object with min/max.

facets

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.

_meta

object

Show Properties

appliedSearchRules

Array of strings

The IDs of search rules that matched and were applied to this request. Returns an empty array when no search rules matched. Use this to verify which search rules are affecting a given search request.

redirect

object

Semantic redirect information. Only present when a semantic match is found for text search queries. When a redirect is returned, the results array will be empty.

Show Properties

url

string

The redirect URL to navigate to. This URL is determined by semantic matching of the search query against configured redirect terms.

affinities

array of objects

User affinity signals derived from the session’s contextual information. Only present when you pass the context and identity parameters and the engine detects meaningful affinity patterns from cart contents and purchase history. The array contains both promotion entries (positive weights for preferred attribute values) and demotion entries (small negative weights for non-preferred values within the same attribute). Entries are grouped by property and sorted by weight in descending order.

Show Properties

property

string

The product attribute the affinity applies to (e.g., "vendor", "product_type", "named_tags.color", "options.Size").

operator

string

The comparison operator. "eq" for promotion entries that boost a specific value. "not_in" for demotion entries that slightly suppress products that don’t match any detected preference for this attribute.

value

string | array of strings

For promotion entries ("eq"): the specific attribute value that was boosted (e.g., "Nike", "Running Shoes"). For demotion entries ("not_in"): an array of all promoted values for this attribute, so products not matching any of them receive a small negative boost.

weight

number

The boost weight applied. Promotion weights range from 0 to 1.2, where higher values indicate stronger preferences. Demotion weights are small negative values proportional to the strongest promotion in the same attribute group. Option-level attributes (e.g., options.Size) receive lower weights than product-level attributes (e.g., vendor).

variantBreakouts

array of objects

Array of variant breakout configurations applied to search. Only present when one or more variant breakouts are active for search requests. Multiple breakouts with different option codes can work simultaneously.

Show Properties

string

The unique identifier of the variant breakout configuration.

name

string

The display name of the variant breakout configuration (e.g., “Gemstone Breakout”, “Color Breakout”).

optionCode

string

The product option code that determines which variants are broken out (e.g., “Stone”, “Color”). Each product is broken out by the first matching option code from the array.

_workflow

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.

Show Properties

type

string

The processing step type. Possible values:

"query-replacement" — The original query was replaced (e.g., by a spelling correction or search rule). The payload contains the corrected query string.
"query-expansion" — Additional related queries were generated to broaden the search. The payload is an array of expanded query strings.
"query-interpretation" — The engine analyzed the query to extract intent signals such as spelling corrections, detected language, and classification. The payload contains the interpretation details.
"intent-modifiers" — AI-powered intent modifiers adjusted the query based on detected shopping intent. The payload contains the modifier actions that were applied.
"ranking-rules" — One or more ranking rules matched and influenced result ordering. The payload lists the applied rules.
"affinity-boosts" — User affinity signals from session context (cart, purchase history) were applied to personalize results. The payload contains the affinity boost details.
"semantic-redirect" — A semantic redirect matched the query. The payload contains the redirect URL.
"rule-applied" — A merchandising rule was applied (browse requests). The payload contains the rule identifier.

payload

string | array | object

The data associated with this processing step. The structure varies by type — see descriptions above.

Response headers

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

Header	Description
`x-request-id`	A unique identifier (ULID) for the request. This matches the `attributionToken` in the response body. Use it to correlate requests across your infrastructure or when contacting support.
`x-layers-build`	The Layers build version that served the request.
`X-Layers-Results-Cache`	Indicates whether the response was served from the results cache. Returns `HIT` when cached results were used, or `MISS` when results were computed fresh. Use this to monitor cache effectiveness and debug performance.
`Link`	Contains `rel="preload"` directives for product images in the response (up to 6 items), enabling browsers and CDNs to begin fetching images before your application processes the JSON body. Each entry includes a responsive `imagesrcset` with multiple sizes. See Early hints for configuration options. Only included when early hints are enabled for your store (enabled by default).

Variant breakouts

When variant breakouts are configured for search, results may include both product tiles and variant tiles. Each result includes a __typename field to identify the tile type:

__typename

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:

product_id

number

The parent product ID. Use this to link back to the full product or group variants from the same product.

variant_id

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 this can be configured per breakout. If the breakout’s “Include Option Value in Title” setting is disabled, the title will be the original product title. See the Variant Breakouts documentation for more details.

POST /storefront/v1/search/running%20shoes/execute

{
  "pagination": {
    "page": 1,
    "limit": 20
  },
  "retrieveFacetCount": true,
  "facets": ["vendor", "product_type"],
  "context": {
    "geo": {
      "country": "US",
      "province": "California"
    },
    "productsInCart": [
      {
        "title": "Nike Air Force 1",
        "productId": "1234567890",
        "variantId": "9876543210"
      }
    ],
    "marketing": {
      "source": "google",
      "medium": "cpc",
      "campaign": "summer-sale"
    },
    "shoppingChannel": "web"
  },
  "identity": {
    "sessionId": "abc123",
    "deviceId": "device-uuid"
  }
}

Browse

Product Search

Content Search

Blocks

Analytics

Facets

Utilities

Text Search: Execute Search

Authorization

Headers

Path parameters

Body

Response

Response headers

Variant breakouts

Variant tile fields

Browse

Product Search

Content Search

Blocks

Analytics

Facets

Utilities

​Authorization

​Headers

​Path parameters

​Body

​Response

​Response headers

​Variant breakouts

​Variant tile fields

Authorization

Headers

Path parameters

Body

Response

Response headers

Variant breakouts

Variant tile fields