Signatures & Parameters

A quick, table-first reference for the argument structure of everything exported from @glood/hydrogen. Object-typed arguments (e.g. GloodConfig, GetSectionsParams) are expanded under Parameter object shapes; full response types live in Types.

All headless calls run against API version (2 | 3, default 3). Functions marked v3-only throw when called on a v2 client.

Client

createGlood(config)

function createGlood(config: GloodConfig): GloodClient

Argument	Type	Required	Description
`config`	`GloodConfig`	Yes	Client configuration. Throws if `apiKey`/`myShopifyDomain` are missing or `version` is not `2`/`3`.

Returns: GloodClient

GloodClient methods

Method	Arguments	Returns
`use(appModuleOrFactory)`	`appModuleOrFactory: GloodAppModule`	`GloodClient` (chainable)
`getEnabledApps()`	—	`GloodApp[]`
`getApp(name)`	`name: AppName` (`'recommendations'`)	`GloodApp \| undefined`
`getInitData()`	—	`InitResponse \| null` (saved `/v3/headless/init` response; read-only)
`setInitData(data)`	`data: InitResponse \| null`	`void` (used internally by `runHeadlessInit`)

App module

recommendations()

function recommendations(): GloodAppModule

Takes no arguments. Pass to client.use(recommendations()).

RecommendationsApp methods

Obtain the app with client.getApp('recommendations').

Method	Arguments	Returns	Notes
`getSections(params)`	`params:` `GetSectionsParams`	`Promise<SectionsResponse>`	v3
`getInit(params?)`	`params?:` `InitParams`	`Promise<InitResponse>`	v3-only
`getRecommendations(params)`	`params:` `RecommendationsParams`	`Promise<RecommendationsResponse \| V2RecommendationsResponse>`	version-aware
`getAutomaticRecommendations(params)`	`params:` `AutomaticRecommendationsParams`	`Promise<AutomaticRecommendationsResponse>`	v3-only
`getTopRecommendations(params)`	`params:` `TopRecommendationsParams`	`Promise<TopRecommendationsResponse>`	v3-only
`sendEvent(params)`	`params:` `HeadlessEventParams`	`Promise<HeadlessEventResponse>`	v3-only
`trackRender(track)`	`track:` `SectionTrack`	`void`	glood:section:render
`trackView(track)`	`track:` `SectionTrack`	`void`	glood:section:view
`trackClick(track)`	`track:` `SectionTrack`	`void`	glood:section:click
`trackAddToCart(track)`	`track:` `SectionTrack`	`void`	glood:section:add_to_cart

Components & hooks

GloodProvider(props)

function GloodProvider(props: GloodProviderProps): React.ReactElement

Prop	Type	Required	Description
`client`	`GloodClient`	Yes	The client from `createGlood()`.
`loaderData`	`any`	Yes	Root loader data (shop/consent context).
`children`	`ReactNode`	Yes	App tree.

Subscribes to Shopify analytics and fires /v3/headless/init on mount (v3).

Hooks

Hook	Arguments	Returns
`useGloodAnalytics()`	—	`GloodClient \| null`
`useGloodInit()`	—	`InitResponse \| null` (v3 init response; `null` until resolved / for v2)
`useGloodInitReady()`	—	`boolean` (true once page-load init has settled)
`useRecommendations(params, options?)`	`params:` `GetSectionsParams`, `options?: { skip?: boolean }`	`UseRecommendationsResult`

UseRecommendationsResult = { sections, data, loading, error, refetch, trackRender, trackView, trackClick, trackAddToCart }.

Standalone functions

All take options: HeadlessRequestOptions as the first argument.

Function	Arguments	Returns	Notes
`fetchRecommendationSections(options, params)`	`params:` `GetSectionsParams`	`Promise<SectionsResponse>`	v3
`fetchHeadlessInit(options, params?)`	`params?:` `InitParams`	`Promise<InitResponse>`	v3-only
`sendHeadlessEvent(options, params)`	`params:` `HeadlessEventParams`	`Promise<HeadlessEventResponse>`	v3-only
`fetchRecommendations(options, params)`	`params:` `RecommendationsParams`	`Promise<RecommendationsResponse \| V2RecommendationsResponse>`	version-aware
`fetchV3Recommendations(options, params)`	`params:` `RecommendationsParams`	`Promise<RecommendationsResponse>`	v3
`fetchV2Recommendations(options, params)`	`params:` `V2RecommendationsParams`	`Promise<V2RecommendationsResponse>`	v2
`fetchAutomaticRecommendations(options, params)`	`params:` `AutomaticRecommendationsParams`	`Promise<AutomaticRecommendationsResponse>`	v3-only
`fetchTopRecommendations(options, params)`	`params:` `TopRecommendationsParams`	`Promise<TopRecommendationsResponse>`	v3-only
`headlessRequest(resource, body, options)`	`resource: string`, `body: Record<string, any>`	`Promise<T>`	low-level POST
`runHeadlessInit(client)`	`client: GloodClient`	`Promise<InitResponse \| null>`	no-op/`null` for v2

Utilities & errors

Export	Arguments	Returns
`checkConsent(requiredConsents, canTrack, analytics)`	`requiredConsents: readonly ConsentType[]`, `canTrack: () => boolean`, `analytics: any`	`boolean`
`getPixelQueue(debug?)`	`debug?: boolean` (default `false`)	`PixelQueue`
`resetPixelQueue()`	—	`void`
`new GloodApiError(message, status, body)`	`message: string`, `status: number`, `body: unknown`	`GloodApiError` (`.status`, `.body`)

Parameter object shapes

GloodConfig

Field	Type	Required	Default	Description
`apiKey`	`string`	Yes	—	Glood storefront token (`gl_sf_*`).
`myShopifyDomain`	`string`	Yes	—	`store-name.myshopify.com`.
`version`	`2 \| 3`	No	`3`	Headless API version.
`apps`	`{ recommendations?: RecommendationsAppConfig }`	No	defaults	Per-app config.
`debug`	`boolean`	No	`false`	Debug logging.
`settings`	`Record<string, any>`	No	—	Passthrough settings.

HeadlessRequestOptions

Field	Type	Required	Default	Description
`apiKey`	`string`	Yes (v3)	—	Storefront token; bearer for v3.
`myShopifyDomain`	`string`	Yes	—	Sent as `x-shop`.
`endpoint`	`string`	No	`https://storefront.glood.ai`	Endpoint override.
`version`	`2 \| 3`	No	`3`	API version.
`debug`	`boolean`	No	`false`	Log request/response.

GetSectionsParams

Field	Type	Required	Description
`pageType`	`PageType`	Yes	Page the visitor is on.
`pageUrl`	`string`	No	Defaults to `window.location.href` in the browser.
`locale`	`string`	No	Defaults to `navigator.language` in the browser.
`productId`	`string \| number`	No	Numeric Shopify product id (product pages).
`cartProductIds`	`Array<string \| number>`	No	Numeric ids in cart.
`sections`	`number[]`	No	Specific section ids (empty = all).
`clientId`	`string`	No	Defaults to the `_glood_client_id` cookie.
`userId`	`string`	No	Defaults to the init `_glood_user_id` cookie.
`customerId`	`string`	No	Shopify customer id.
`market`	`string`	No	Market id.
`currency`	`string`	No	Currency code.
`cartValue`	`string`	No	Cart total.
`collection`	`number`	No	Numeric collection id.
`qs`	`string`	No	Query string for experience assignment.
`preview`	`boolean`	No	Include disabled sections.

InitParams

Field	Type	Required	Description
`userId`	`string`	No	Replays a persisted visitor id (returning visitor).
`clientId`	`string`	No	Defaults to the `_glood_client_id` cookie.
`customerId`	`string`	No	Shopify customer id.
`pageType`	`PageType`	No	Current page type.
`pageUrl`	`string`	No	Defaults to `window.location.href`.

RecommendationQuery

Field	Type	Required	Description
`id`	`string`	Yes	Result key in the response.
`recommendationType`	`string`	Yes	One of `RecommendationType` — commonly `'similar_products'` / `'bought_together'`.
`productIds`	`Array<string \| number>`	Yes	Anchor product ids (v3: up to 10).
`maxRecommendations`	`number`	No	Max results.
`creationType`	`string`	No	One of `CreationType`: `'manual'` \| `'automatic'`.
`view`	`RecommendationView`	Yes	`'product_details'` or `'product_ids'`.

RecommendationsParams

Field	Type	Required	Description
`queries`	`RecommendationQuery[]`	Yes	Up to 5 (v3).
`clientId`	`string`	No	Visitor client id.
`userId`	`string`	No	Visitor user id.
`customerId`	`string`	No	Shopify customer id.

V2RecommendationsParams

Field	Type	Required	Description
`queries`	`RecommendationQuery[]`	Yes	`similar_products` only on v2.

AutomaticRecommendationsParams

Field	Type	Required	Description
`productIds`	`number[]`	Yes	Anchor product ids.
`view`	`RecommendationView`	Yes	`'product_details'` or `'product_ids'`.
`recommendationType`	`'similar_products'`	No	Only value supported.
`maxRecommendations`	`number`	No	Max results.
`filter`	`Record<string, any>`	No	Vendor/tag/variant filters.
`pagination`	`{ cursor?: string \| null; limit?: number }`	No	Cursor pagination (limit default 12).

TopRecommendationsParams

Field	Type	Required	Description
`strategy`	`TopStrategy`	Yes	`'BESTSELLERS'` \| `'NEW_ARRIVALS'` — uppercase.
`view`	`RecommendationView`	Yes	`'product_details'` or `'product_ids'`.
`strategyOptions`	`{ salesTimePeriod?: 7 \| 15 \| 30; bestsellerMetric?: BestsellerMetric }`	No	`bestsellerMetric`: `'revenue'` \| `'quantity'` \| `'orders'`.
`query`	`string`	No	Full-text catalog search.
`filter`	`Record<string, any>`	No	Vendor/tag/price/etc. filters.
`facets`	`TopFacet[]`	No	`'vendor' \| 'product_type' \| 'tag' \| 'price'`.
`pagination`	`{ cursor?: string \| null; limit?: number }`	No	Cursor pagination (limit default 24, max 100).

HeadlessEventParams

Field	Type	Required	Description
`event`	`{ id, name, type, timestamp, data?, customData? }`	Yes	`type` is `'standard' \| 'custom'`; `timestamp` ISO, within ±2 days.
`channel`	`HeadlessEventChannel`	No	`'mobile' \| 'headless' \| 'hydrogen'` (default `'hydrogen'`).
`sessionId`	`string`	No	Defaults to the session cookie (server requires it).
`clientId`	`string`	No	At least one of `clientId`/`userId` required.
`userId`	`string`	No	See above.
`customerId`	`string`	No	Shopify customer id.
`experience`	`string \| null`	No	Assigned experience id.
`pageType`	`string`	No	Page type.
`pageUrl`	`string`	No	Page URL.

Additional fields (e.g. cart, customer, customer_privacy, device) are passed through in the API’s snake_case wire format.

SectionTrack

Field	Type	Required	Description
`section`	`string`	No	Glood section id.
`sectionServeId`	`string`	No	`section_serve_id` from the sections response.
`requestId`	`string`	No	`request_id` from the sections response.
`page`	`string`	No	Page type of the interaction.
`parent`	`{ productId?: string; variantId?: string }`	No	Context product (e.g. the PDP product).
`products`	`SectionTrackProduct[]`	No	Products involved (`{ productId, variantId?, quantity? }`).

Enums & value sets

Several fields accept a fixed set of values. recommendationType / creationType are typed as string in the SDK (for forward-compat), but only the values below are meaningful.

RecommendationType (`recommendationType`)

Value	Notes
`similar_products`	Supported on every recommendation endpoint (v2, v3, automatic).
`bought_together`	v3 `/recommendations` only.
`recently_viewed`
`cross_sell`
`bestsellers`
`trending`
`personalized`
`recent_launch`
`collections`
`purchases`
`promoted`
`custom`
`email_recommendations`

fetchV3Recommendations / getRecommendations accept any of the above, but the backend currently returns results only for similar_products and bought_together. fetchV2Recommendations and fetchAutomaticRecommendations support similar_products only.

CreationType (`creationType`)

Value
`manual`
`automatic`

RecommendationView (`view`)

Value	Result item shape
`product_details`	Full product objects (`RecommendedProduct`).
`product_ids`	`{ product_id: number }`.

TopStrategy (`strategy`)

Uppercase — maps directly to the backend enum.

Value
`BESTSELLERS`
`NEW_ARRIVALS`

BestsellerMetric (`strategyOptions.bestsellerMetric`)

Value
`revenue`
`quantity`
`orders`

strategyOptions.salesTimePeriod accepts 7, 15, or 30 (days).

Value
`vendor`
`product_type`
`tag`
`price`

HeadlessEventChannel (`channel`)

Value	Notes
`hydrogen`	Default for this SDK.
`headless`
`mobile`

Event type (`event.type`)

Value
`standard`
`custom`

PageType (`pageType`)

product_page, collection, home, cart, order_confirm, other, blog, ajax_cart, 404, checkout, returns analytics, marketing, preferences, sale_of_data

Event names (`event.name`)

Standard Shopify analytics events the SDK forwards: page_viewed, product_viewed, collection_viewed, cart_viewed, search_submitted, product_added_to_cart, product_removed_from_cart. Custom attribution events: glood:section:render, glood:section:view, glood:section:click, glood:section:add_to_cart.

Types

Full request/response type definitions.

Recommendations API

Standalone function usage and endpoints.

Client

createGlood(config)

GloodClient methods

App module

recommendations()

RecommendationsApp methods

Components & hooks

GloodProvider(props)

Hooks

Standalone functions

Utilities & errors

Parameter object shapes

GloodConfig

HeadlessRequestOptions

GetSectionsParams

InitParams

RecommendationQuery

RecommendationsParams

V2RecommendationsParams

AutomaticRecommendationsParams

TopRecommendationsParams

HeadlessEventParams

SectionTrack

Enums & value sets

RecommendationType (`recommendationType`)

CreationType (`creationType`)

RecommendationView (`view`)

TopStrategy (`strategy`)

BestsellerMetric (`strategyOptions.bestsellerMetric`)

TopFacet (`facets[]`)

HeadlessEventChannel (`channel`)

Event type (`event.type`)

PageType (`pageType`)

Event names (`event.name`)

See Also

Types

Recommendations API

​Client

​createGlood(config)

​GloodClient methods

​App module

​recommendations()

​RecommendationsApp methods

​Components & hooks

​GloodProvider(props)

​Hooks

​Standalone functions

​Utilities & errors

​Parameter object shapes

​GloodConfig

​HeadlessRequestOptions

​GetSectionsParams

​InitParams

​RecommendationQuery

​RecommendationsParams

​V2RecommendationsParams

​AutomaticRecommendationsParams

​TopRecommendationsParams

​HeadlessEventParams

​SectionTrack

​Enums & value sets

​RecommendationType (recommendationType)

​CreationType (creationType)

​RecommendationView (view)

​TopStrategy (strategy)

​BestsellerMetric (strategyOptions.bestsellerMetric)

​TopFacet (facets[])

​HeadlessEventChannel (channel)

​Event type (event.type)

​PageType (pageType)

​ConsentType (pixel.consent[])

​Event names (event.name)

​See Also

Types

Recommendations API

Client

createGlood(config)

GloodClient methods

App module

recommendations()

RecommendationsApp methods

Components & hooks

GloodProvider(props)

Hooks

Standalone functions

Utilities & errors

Parameter object shapes

GloodConfig

HeadlessRequestOptions

GetSectionsParams

InitParams

RecommendationQuery

RecommendationsParams

V2RecommendationsParams

AutomaticRecommendationsParams

TopRecommendationsParams

HeadlessEventParams

SectionTrack

Enums & value sets

RecommendationType (`recommendationType`)

CreationType (`creationType`)

RecommendationView (`view`)

TopStrategy (`strategy`)

BestsellerMetric (`strategyOptions.bestsellerMetric`)

TopFacet (`facets[]`)

HeadlessEventChannel (`channel`)

Event type (`event.type`)

PageType (`pageType`)

ConsentType (`pixel.consent[]`)

Event names (`event.name`)

See Also