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.

publication_ids
(string | integer)[]

Optional. Numeric Shopify publication (sales channel) ids. When present, only products published on at least one of these channels are returned and the default "published to the Online Store" gate is replaced by this filter; market and B2B filters still apply. A single id may be sent without the array wrapper. Each id must be one the merchant enabled under Settings → Sales channels; unknown ids return 400. The id is the numeric tail of gid://shopify/Publication/.

Maximum array length: 50
Pattern: ^[0-9]+$
Example:
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.