> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glood.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Signatures & Parameters
> Argument structure for every hook, component, and function exported by @glood/hydrogen, in table form.
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](#parameter-object-shapes); full response types live in [Types](/for-developers/glood-hydrogen-sdk/api-reference/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)
```typescript theme={null}
function createGlood(config: GloodConfig): GloodClient
```
| Argument | Type | Required | Description |
| -------- | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `config` | [`GloodConfig`](#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()
```typescript theme={null}
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`](#getsectionsparams) | `Promise` | v3 |
| `getInit(params?)` | `params?:` [`InitParams`](#initparams) | `Promise` | **v3-only** |
| `getRecommendations(params)` | `params:` [`RecommendationsParams`](#recommendationsparams) | `Promise` | version-aware |
| `getAutomaticRecommendations(params)` | `params:` [`AutomaticRecommendationsParams`](#automaticrecommendationsparams) | `Promise` | **v3-only** |
| `getTopRecommendations(params)` | `params:` [`TopRecommendationsParams`](#toprecommendationsparams) | `Promise` | **v3-only** |
| `sendEvent(params)` | `params:` [`HeadlessEventParams`](#headlesseventparams) | `Promise` | **v3-only** |
| `trackRender(track)` | `track:` [`SectionTrack`](#sectiontrack) | `void` | glood:section:render |
| `trackView(track)` | `track:` [`SectionTrack`](#sectiontrack) | `void` | glood:section:view |
| `trackClick(track)` | `track:` [`SectionTrack`](#sectiontrack) | `void` | glood:section:click |
| `trackAddToCart(track)` | `track:` [`SectionTrack`](#sectiontrack) | `void` | glood:section:add\_to\_cart |
## Components & hooks
### GloodProvider(props)
```typescript theme={null}
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`](#getsectionsparams), `options?: { skip?: boolean }` | `UseRecommendationsResult` |
`UseRecommendationsResult` = `{ sections, data, loading, error, refetch, trackRender, trackView, trackClick, trackAddToCart }`.
## Standalone functions
All take `options:` [`HeadlessRequestOptions`](#headlessrequestoptions) as the first argument.
| Function | Arguments | Returns | Notes |
| ------------------------------------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------- |
| `fetchRecommendationSections(options, params)` | `params:` [`GetSectionsParams`](#getsectionsparams) | `Promise` | v3 |
| `fetchHeadlessInit(options, params?)` | `params?:` [`InitParams`](#initparams) | `Promise` | **v3-only** |
| `sendHeadlessEvent(options, params)` | `params:` [`HeadlessEventParams`](#headlesseventparams) | `Promise` | **v3-only** |
| `fetchRecommendations(options, params)` | `params:` [`RecommendationsParams`](#recommendationsparams) | `Promise` | version-aware |
| `fetchV3Recommendations(options, params)` | `params:` [`RecommendationsParams`](#recommendationsparams) | `Promise` | v3 |
| `fetchV2Recommendations(options, params)` | `params:` [`V2RecommendationsParams`](#v2recommendationsparams) | `Promise` | v2 |
| `fetchAutomaticRecommendations(options, params)` | `params:` [`AutomaticRecommendationsParams`](#automaticrecommendationsparams) | `Promise` | **v3-only** |
| `fetchTopRecommendations(options, params)` | `params:` [`TopRecommendationsParams`](#toprecommendationsparams) | `Promise` | **v3-only** |
| `headlessRequest(resource, body, options)` | `resource: string`, `body: Record` | `Promise` | low-level POST |
| `runHeadlessInit(client)` | `client: GloodClient` | `Promise` | 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` | 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` | 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`](#recommendationtype-recommendationtype) — commonly `'similar_products'` / `'bought_together'`. |
| `productIds` | `Array` | Yes | Anchor product ids (v3: up to 10). |
| `maxRecommendations` | `number` | No | Max results. |
| `creationType` | `string` | No | One of [`CreationType`](#creationtype-creationtype): `'manual'` \| `'automatic'`. |
| `view` | `RecommendationView` | Yes | `'product_details'` or `'product_ids'`. |
### RecommendationsParams
| Field | Type | Required | Description |
| ------------ | ----------------------------------------------- | -------- | -------------------- |
| `queries` | [`RecommendationQuery[]`](#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[]`](#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` | 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` | 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).
### TopFacet (`facets[]`)
| 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`
### ConsentType (`pixel.consent[]`)
`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`.
## See Also
Full request/response type definitions.
Standalone function usage and endpoints.