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

Filter definitions request (DB-driven, no live counts).

collection

Collection id to resolve a collection-scoped tree. String or integer.

tree
integer

Explicit filter tree id (overrides target-page resolution).

target_page
enum<string>

Page whose tree to resolve.

Available options:
search,
collection
target_id
integer

Target object id (e.g. collection id).

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:
include_values
boolean
default:true

Include each facet's selectable values.

include_disabled
boolean
default:false

Include disabled filters.

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

Filter definitions

DB-driven facet definitions for the resolved tree.

facets
object[]

Facet definitions, sorted by position.

tree
object | null

Resolved tree, or the empty-fallback tree when none is configured.

metadata
object

Response metadata.