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.

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.