Skip to main content
POST
cURL
Each product carries trending_rank and sales_rank — shop-wide ranks refreshed daily; see the field reference.

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

Example:

"shop.myshopify.com"

Body

application/json

Page context and section request payload

page_url
string
required

Full URL of the current page

page_type
enum<string>
required

Type of the current page

Available options:
home,
product,
collection,
cart,
checkout,
order_status,
search,
other
locale
string
required

BCP 47 locale code for the response language

Example:

"en"

client_id
string

Client/device identifier

user_id
string

Anonymous visitor identifier

customer_id
string

Shopify customer ID for authenticated visitors

product_id
integer

ID of the current product (required for product pages)

cart_product_ids
integer[]

Product IDs currently in the visitor's cart

market
string

Shopify market handle for market-specific content

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:
sections
string[]

Specific section IDs to fetch. Omit to fetch all eligible sections for the page.

placed_sections
string[]

Section IDs already rendered on the page (used to avoid duplicates)

preview
boolean

When true, returns sections in preview/draft mode

tags
string[]

Product tags to scope recommendation results

collection
string

Collection handle for collection-page context

currency
string

Currency code for pricing (defaults to shop currency)

zipcode
string

Visitor's zip/postal code for location-based recommendations

cart_value
number

Total value of the visitor's current cart

Response

Sections with product details

request_id
string

Unique identifier for this request (use for event tracking)

visit_id
string

Current visit session identifier

sections
object[]
product
object

The current page's product (populated on product pages)

token
string

Refreshed session token

config
object

Shop configuration snapshot (same shape as HeadlessInitResponse.config)

experience
object

A/B test experience assignment for this request