Search API: Semantic Catalog Search

curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/execute \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "attributes": [
    "<string>"
  ],
  "search_id": "<string>",
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123
  },
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "discountEntitlements": [
    {
      "entitled": {
        "all": true,
        "products": [
          "<string>"
        ],
        "variants": [
          {}
        ],
        "collections": [
          "<string>"
        ]
      },
      "discount": {
        "type": "<string>",
        "value": 123
      }
    }
  ],
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>"
  }
}
'

{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}

POST

https://app.uselayers.com/api/storefront/v1

{searchQuery}

execute

Search API: Semantic Catalog Search

curl --request POST \
  --url https://app.uselayers.com/api/storefront/v1/search/{searchQuery}/execute \
  --header 'Accept: <accept>' \
  --header 'Content-Type: <content-type>' \
  --header 'X-Storefront-Access-Token: <x-storefront-access-token>' \
  --data '
{
  "attributes": [
    "<string>"
  ],
  "search_id": "<string>",
  "tuning": {
    "textualWeight": 123,
    "visualWeight": 123,
    "multipleFactor": 123,
    "minimumMatch": 123
  },
  "filter_group": {},
  "pagination": {
    "page": 123,
    "limit": 123
  },
  "facets": [
    "<string>"
  ],
  "retrieveFacetCount": true,
  "includeFacetRanges": true,
  "discountEntitlements": [
    {
      "entitled": {
        "all": true,
        "products": [
          "<string>"
        ],
        "variants": [
          {}
        ],
        "collections": [
          "<string>"
        ]
      },
      "discount": {
        "type": "<string>",
        "value": 123
      }
    }
  ],
  "identity": {
    "deviceId": "<string>",
    "sessionId": "<string>",
    "customerId": "<string>"
  }
}
'

{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}

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

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, and first_or_matched_variant. 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. See the Search API Optimization Guide.

tuning

object

Parameters to fine-tune the search results.

Show Properties

textualWeight

decimal

Weight given to textual similarity (0-1). Must be provided together with visualWeight.

visualWeight

decimal

Weight given to visual similarity (0-1). Must be provided together with textualWeight.

multipleFactor

integer

Multiplier applied to the search results.

minimumMatch

decimal

Minimum match score threshold (0-1) for including results.

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 is the percentage (e.g., 10 for 10% off). For FIXED_AMOUNT, this is the currency amount.

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.

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.

Product Score Fields

When search results are returned, each product may include scoring information that explains how the result was ranked:

hybridScore

number

The combined relevance score for the product, calculated from both textual and visual similarity. This score is normalized between 0 and 1, where higher values indicate greater relevance to the search query.

scoreContributions

array

An array of objects detailing how each component of the search query contributed to the product’s final score. Each contribution includes:

type: Either “text” or “image” indicating the type of similarity match
query_label: The specific query term or expansion that contributed to the score
normalized_score: The normalized contribution value (0-1)
similarity_score: The raw similarity score before normalization

{
    "results": [
        {
            "id": 7003338965178,
            "title": "SUPREME SEALLINE SEE POUCH SMALL",
            "body_html": "The Supreme Sealline See Pouch Small is a versatile and waterproof storage solution that seamlessly marries utility and style. With its clear window for easy visibility and the iconic Supreme branding, it's a sought-after accessory for those who appreciate keeping their essentials dry while making a fashion statement, whether at the beach or in the city..",
            "vendor": "SUPREME",
            "product_type": "Accessories",
            "created_at": 1644047925,
            "handle": "supreme-pouch-44370ss18a32-sm",
            "updated_at": 1698280024,
            "published_at": 1644047925,
            "tags": [
                "consignment",
            ],
            "images": [
                {
                    "alt": "SUPREME POUCH",
                    "src": "https://cdn.shopify.com/s/files/1/0588/3677/9194/products/ss18_supreme_tnf_pouch_blk_2-l_5fb1316e-22f7-4702-9953-57f3fbdda5be.jpg?v=1644047927",
                    "width": 800,
                    "height": 534,
                    "variant_ids": []
                }
            ],
            "metafields": {
                "product": {
                    "alias": "SEALLINE SEE POUCH SMALL",
                    "colorway": "BLACK",
                    "styleCode": "SS18A30 BLACK",
                    "yearOfRelease": 2018,
                    "searchColor": [
                        "black"
                    ]
                }
            },
            "available": true,
            "price_range": {
                "from": 30,
                "to": 30
            }
        }
    ],
    "totalResults": 1000,
    "page": 1,
    "totalPages": 20,
    "facets": {
        "vendor": {
            "ADIDAS": 30,
            "JORDAN": 336,
            "NEW BALANCE": 15,
            "NIKE": 384,
            "REEBOK": 4,
            "SUPREME": 624,
            "VANS": 32
        }
    },
    "attributionToken": "2y10smI2dB7XZXXFJsLUELltgueq8NRdcRD3U8djkLqxQmaVMvg1lSCf2"
}

Prepare Search Image Search

⌘I

Browse

Search

Visual Discovery

Analytics

Utilities

Search API: Semantic Catalog Search

Authorization

Headers

Path Parameters

Body

Response

Product Score Fields

Browse

Search

Visual Discovery

Analytics

Utilities

​Authorization

​Headers

​Path Parameters

​Body

​Response

​Product Score Fields

Authorization

Headers

Path Parameters

Body

Response

Product Score Fields