Skip to main content
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)

Returns: GloodClient

GloodClient methods

App module

recommendations()

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

RecommendationsApp methods

Obtain the app with client.getApp('recommendations').
options.events narrows the forwarded standard events (default: all). Pass to client.use(search()). Search is pinned to v1 regardless of the client version.

SearchApp methods

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

Components & hooks

GloodProvider(props)

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

Hooks

UseRecommendationsResult = { sections, data, loading, error, refetch, trackRender, trackView, trackClick, trackAddToCart }. UseSearchResult = { products, data, loading, error, refetch, trackSearch, trackResultView, trackResultClick, trackAddToCart, trackFilter }. UseInstantSearchResult = { data, products, suggestions, collections, pages, loading, error, refetch }. UseSearchConfigResult = { config, loading, error, refetch }.

Standalone functions

All take options: HeadlessRequestOptions as the first argument.
Search fetchers take options: FetchSearchOptions (the same HeadlessRequestOptions) and are pinned to v1 internally, defaulting endpoint to https://search.glood.ai.

Utilities & errors

Parameter object shapes

GloodConfig

HeadlessRequestOptions

GetSectionsParams

InitParams

RecommendationQuery

RecommendationsParams

V2RecommendationsParams

AutomaticRecommendationsParams

TopRecommendationsParams

HeadlessEventParams

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

SectionTrack

SearchInitParams

All optional. In the browser visitorId / clientId default from the Glood cookies.

SearchConfigParams

InstantSearchParams

FiltersParams

FilterAggregationsParams

SearchParams

ImageSearchParams

SearchTrack

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)

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)

RecommendationView (view)

TopStrategy (strategy)

Uppercase — maps directly to the backend enum.

BestsellerMetric (strategyOptions.bestsellerMetric)

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

TopFacet (facets[])

HeadlessEventChannel (channel)

Event type (event.type)

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, and for search: glood:instant_search_triggered, glood:search_result_rendered, glood:search_result_clicked, glood:search:add_to_cart, glood:search_filter_updated.

SearchView (view)

Product render mode for search endpoints:

SearchSort (sort)

relevance (default), title_asc, title_desc, price_asc, price_desc, best_selling, oldest, newest.

InstantSearchObject (objects[])

product, collection, page, article, query_suggestion, autocorrect.

Search event channel (channel)

The search events API (sendSearchEvent) uses uppercase channels: HYDROGEN, HEADLESS, MOBILE. sendSearchEvent defaults to HYDROGEN.

See Also

Types

Full request/response type definitions.

Recommendations API

Standalone function usage and endpoints.