Search API: Similar Products

How results are served

Similar products results are precomputed and cached for fast response times. The system runs the full ranking pipeline — combining vector similarity with behavioral signals — and stores the top results for each product. When you call this endpoint, results are served from the precomputed cache. If no precomputed data exists for a product (for example, a newly added product), the system falls back to real-time vector search automatically. Precomputed results are refreshed daily and incrementally when a product’s embeddings change. All request parameters (filters, facets, pagination, and sort orders) work the same regardless of whether results are served from cache or computed in real time.

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

searchProductId

integer

required

The ID of the product for which you want to find similar products.

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.

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.

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.

defaultSelectedOptions

array

Specify which product variants should be selected by default in the first_or_matched_variant field.

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

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.

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.

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.

totalResults

number

The total number of results.

page

number

The current page number.

totalPages

number

The total number of pages.

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. Empty values and literal "null" strings are automatically excluded from facet results.

attributionToken

string

The attribution token.

_meta

object

Show Properties

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.

POST /storefront/v1/search/product/7003338965178

{
  "pagination": {
    "page": 1,
    "limit": 20
  },
  "context": {
    "geo": {
      "country": "US"
    },
    "shoppingChannel": "web"
  },
  "identity": {
    "sessionId": "abc123",
    "deviceId": "device-uuid"
  }
}

Browse

Product Search

Content Search

Blocks

Analytics

Facets

Utilities

Search API: Similar Products

How results are served

Authorization

Headers

Path parameters

Body

Response

Browse

Product Search

Content Search

Blocks

Analytics

Facets

Utilities

​How results are served

​Authorization

​Headers

​Path parameters

​Body

​Response

How results are served

Authorization

Headers

Path parameters

Body

Response