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

Session context. All fields optional.

Search session bootstrap input (from initSchema). Every field is optional; send the identity triple you have so the visitor profile and history resolve correctly.

page_type
enum<string>

Type of the page the session starts on. Used only for context/attribution.

Available options:
product_page,
collection,
home,
cart,
order_confirm,
blog,
ajax_cart,
404,
checkout,
returns,
search,
other
page_url
string

Full URL of the page the session starts on.

session_id
string

Browsing-session id (defaulted from the SDK session cookie). Ties the visit to a session for analytics.

locale
string
default:en-US

BCP-47 locale for locale-aware indexes and the echoed metadata.

Example:

"en-US"

market
integer

Shopify market id for market-aware pricing / catalog.

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:
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

Visitor context, history, lean config and token

Session bootstrap payload (from getHeadlessInitResponse): identity, visitor history, lean feature config, storefront token and a fresh visit id. Unlike the config endpoint it carries NO filter definitions and NO filter tree.

visit_id
string

Fresh UUID identifying this search session. Echo it as session_id when sending events for this session.

Example:

"3c90c3cc-0d44-4b50-8888-8dd25736052a"

visitor_id
string | null

Anonymous visitor id echoed from the request (null if none was sent). Persist it on the client.

client_id
string | null

Client/device identifier echoed from the request, or null.

customer_id
string | null

Shopify customer id echoed from the request when the shopper is authenticated, or null.

visitor
object

The visitor's recent activity, used to seed personalization.

config
object

Lean feature-flag config (same shape as the config endpoint's config, produced by the same getHeadlessConfigResponse). No filter definitions, no filter tree, no templates.

token
string | null

Shopify storefront access token for direct Storefront API calls, or null.

metadata
object

Response metadata.