Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-shop
string
required

Shopify store URL. Resolves the shop for the request (headless does not accept ?shop=).

Example:

"shop.myshopify.com"

Body

application/json

Request body

Instant search request. Union of the legacy instant-results, instant-suggest and trending inputs.

query
string
default:""

Search term. Required but may be an empty string (empty / too-short queries return the trending block).

Example:

"sho"

locale
string
default:en-US

BCP-47 locale.

market
integer

Shopify market id.

limit
integer

Per-type result limit.

Required range: 1 <= x <= 100
objects
enum<string>[]

Which result blocks to return. Defaults to config.instant_search_objects. query_suggestion/auto_suggestion -> keyword suggestions; autocorrect -> spell-correct.

Available options:
product,
collection,
page,
article,
blog,
query_suggestion,
auto_suggestion,
autocorrect
view
enum<string>
default:product_details

Product render mode.

Available options:
product_details,
product_ids

Options for the empty-state trending block.

visitor_id
string

Anonymous device/browser UID (the gl_s_uid cookie). The primary personalization key; stays stable when a customer logs in.

client_id
string

Per-session / per-device identifier.

customer_id
string

Shopify customer id. Present only when the shopper is logged in; enables customer-level personalization.

Response

Instant search results

Instant search results: products / collections / pages / articles + suggestions + autocorrect + trending.

query
string

Echo of the requested query.

corrected_query
string | null

Convenience mirror of autocorrect.corrected_query; null when no correction.

autocorrect
object | null

Spell-correction result, or null when not requested / disabled.

suggestions
object[]

Keyword suggestions.

products
object

Product results block.

collections
object

Collection results block.

pages
object

Page results block.

articles
object

Article results block.

Populated only when the query is empty / below the minimum length; otherwise empty arrays.

metadata
object

Response metadata.