Product Discovery

Overview

Use product discovery to power search bars, product detail pages, and catalog browsers across any merchant on the internet. Both products.search and products.details are async jobs - they return a refId, and results arrive once the background work completes. See Polling or Webhooks for how to handle the async pattern.

Prerequisites

import HenrySDK from '@henrylabs/sdk';

const henry = new HenrySDK({
	apiKey: process.env.HENRY_SDK_API_KEY!,
});

Search the catalog

Kick off a product search

Call products.search with a text query and optional filters. Returns immediately with a refId.

const search = await henry.products.search({
  type: 'global',
  filters: {
    type: 'text',
    query: 'Nike Air Max',
    country: 'US',
    price: { min: 50, max: 300, currency: 'USD' },
    sortBy: 'price-low-to-high',  // or 'price-high-to-low'
    supportedOnly: true,          // only checkout-supported merchants
    merchants: ['nike.com', 'footlocker.com'], // optional: restrict to these merchants
  },
  limit: 20,              // 1–100, default 20
  mode: 'async',          // or 'sync' to wait up to 30s for results
});

console.log(search.refId, search.status);
// → "prs-ref_3fa8..." "processing"

Poll for results

Use products.pollSearch to check status until it’s "complete" or "failed". See Polling for the reusable helper and strategies.

const result = await henry.products.pollSearch({ refId: search.refId });
// result.status: "pending" | "processing" | "complete" | "failed"

Read the results

const { products, pagination } = result.result!;

for (const product of products) {
  console.log({
    name: product.name,
    price: `${product.price?.value} ${product.price?.currency}`,
    merchant: product.merchant,
    link: product.link,       // use this as the cart item `link`
    inStock: product.availability === 'in_stock',
  });
}

// Paginate with the cursor
if (pagination.nextCursor) {
  const nextPage = await henry.products.search({
    type: 'global',
    filters: { type: 'text', query: 'Nike Air Max' },
    cursor: Number(pagination.nextCursor),
  });
}

Fetch product details

If you need more granular product information, such as available options and pricing, call products.details with the link from search for the full enriched payload.

Request product details

const detailJob = await henry.products.details({
  link: 'https://www.nike.com/t/air-max-270-shoes/AH8050-002',
  country: 'US',          // optional default country
  location: { postalCode: '94103' }, // optional - for location-dependent merchants
  selectedOptions: ['regular'], // optional - resolve the next option axis (positional)
  skipCache: false,       // true to bypass cached details
  mode: 'async',          // or 'sync' to wait up to 30s for results
});

console.log(detailJob.refId, detailJob.status);
// → "prd-ref_3fa8..." "processing"

Poll for results

Use products.pollDetails to check status. See Polling for the reusable helper.

const detail = await henry.products.pollDetails({ refId: detailJob.refId });
// detail.status: "pending" | "processing" | "complete" | "failed"

Read the enriched product

const product = detail.result;

console.log({
  name: product?.name,
  price: product?.price,
  options: product?.options,    // recursive option tree: per-value availability, link, price
  featuredImage: product?.images?.find(i => i.isFeatured)?.url,
  affiliateLink: product?.affiliateLink,  // monetized link, when available
});

availability is one of in_stock, limited_stock, out_of_stock, preorder, backorder, or discontinued. out_of_stock is temporary - keep the product and re-check it later. discontinued means the merchant no longer offers the product, or the specific variant your link names - drop it from your catalog rather than re-polling. A discontinued response carries no price, sku, or images: Henry never substitutes a surviving variant’s figures for one the merchant removed. The options tree still lists what the merchant sells now, with each value’s own images.Each value in the options tree carries its own availability, a link naming that exact variant, and - where the merchant exposes it - its own price / originalPrice. Variants of one product do not always share a price, and the product-level price is the lowest in-stock figure for the featured variant group, so a catalog sync should prefer per-variant prices from the option tree and fall back to the product-level price only when a value carries none. One details call on the base product URL returns the whole tree - no per-variant calls needed.

Henry caches product details internally. If details for a link are already fresh, pollDetails will return "complete" on the very first call.

Affiliate links

When one of Henry’s affiliate networks covers the merchant, the result includes an affiliateLink — a Henry-branded URL (https://api.henrylabs.ai/v1/go/...) that redirects through the affiliate network to the same product. Commissions from purchases made through it attribute to your app, and end-users see a henrylabs.ai link instead of a raw tracking domain. The two link fields have distinct jobs:

link — the merchant’s product URL. Use this for every API call (products.details, cart items, and so on).
affiliateLink — a Henry-branded URL for end-users to click (in your UI, emails, or chat responses). Never pass it back to the API: it redirects through the affiliate network’s tracking domain rather than resolving to the merchant, so Henry can’t resolve products from it.

The field is omitted when no network covers the merchant.

products.details rejects affiliate/tracking URLs in link with a validation error — wild.link and other known network redirect domains. If you stored an affiliateLink, keep the link from the same response alongside it for API calls.

Image search

Search by image instead of text. Pass a URL, data URL, or base64 payload to find visually similar products. Results combine web-wide visual matches with exact and similar products from Henry’s own product-image catalog. With supportedOnly: true, results come only from Henry’s catalog, so every product returned can be bought through Henry.

// Search with an image URL
const imageSearch = await henry.products.search({
	type: 'global',
	filters: {
		type: 'image',
		imageUrl: 'https://static.nike.com/a/images/t_web_pdp_535_v2/f_auto/example.png',
		country: 'US',
	},
	limit: 10,
	mode: 'async',
});

// Poll the same way as text search
const result = await henry.products.pollSearch({ refId: imageSearch.refId });

You can also pass a base64-encoded image:

const imageSearch = await henry.products.search({
	type: 'global',
	filters: {
		type: 'image',
		imageUrl: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',
		country: 'US',
	},
	limit: 5,
});

Search one merchant by image

Add filters.imageUrl to a merchant search to find visually similar products in that merchant’s catalog. Results come only from Henry’s product-image catalog, so they’re available for merchants whose catalog Henry has prepared for image search. Other merchants return a 400 error.

const merchantImageSearch = await henry.products.search({
	type: 'merchant',
	filters: {
		merchant: 'zara.com',
		imageUrl: 'https://static.zara.net/photos/example.jpg',
	},
	limit: 10,
	mode: 'sync',
});

Sync mode

All async operations support mode: "sync", which waits up to 30 seconds for the operation to complete before returning. This can simplify your code for quick lookups by avoiding polling entirely.

// Sync mode - returns results directly (no polling needed)
const search = await henry.products.search({
	type: 'global',
	filters: { type: 'text', query: 'Nike Air Max' },
	limit: 5,
	mode: 'sync',
});

// If the search completed within 30s, results are already here
if (search.status === 'complete') {
	console.log(search.result?.products);
}

If the operation takes longer than 30 seconds, sync mode returns with a non-terminal status and you’ll need to poll normally. For operations that may take longer (e.g. large searches), use mode: "async" with Polling.

Merchant search

Use type: 'merchant' to search within a specific merchant’s catalog. Pass the merchant name, host, or any URL from that merchant.

const search = await henry.products.search({
	type: 'merchant',
	filters: {
		merchant: 'nike.com',
		options: { size: 'M', color: 'black' }, // variant filters - values or option codes
	},
	query: 'running shoes', // optional text query within the merchant
	limit: 20,
	mode: 'sync',
});

Merchant search accepts a case-insensitive name (e.g. "Nike"), a host (e.g. "nike.com"), or any URL from the merchant. When query is omitted, the merchant’s catalog browse is returned.

Search one category

Pass filters.category to page through one category of a merchant’s catalog, or to search within it. Get the merchant’s categories from searchFilters.category on merchants.retrieve.

const search = await henry.products.search({
	type: 'merchant',
	filters: { merchant: 'kith.com', category: 'Mens Footwear - Sneakers' },
	query: 'dunk', // optional - omit to page through the whole category
	mode: 'sync',
});

Category search is available for merchants that list searchFilters.category (Shopify stores and zara.com). Other merchants, and categories the merchant doesn’t have, return a 400. category can’t be combined with filters.imageUrl. A page may contain fewer than limit results - page until nextCursor is null.

Search parameters reference

Top-level parameters

Parameter	Type	Description
`type`	`"global" \| "merchant"`	Required. `"global"` for cross-merchant search, `"merchant"` for single-merchant
`filters`	`object`	Required. Search filters (see below)
`query`	`string`	Optional text query (merchant search only)
`limit`	`number`	Results per page - `1` to `100`, default `20`
`cursor`	`integer`	Pagination cursor from a previous response
`mode`	`"async" \| "sync"`	`"async"` (default) returns immediately; `"sync"` waits up to 30s
`skipCache`	`boolean`	Bypass cached responses and force a fresh search. Default `false`

Parameter	Type	Description
`filters.type`	`"text" \| "image"`	Required. Text query or image-based search
`filters.query`	`string`	Required for text. Full-text search term
`filters.imageUrl`	`string`	Required for image. HTTP URL, data URL, or base64 payload
`filters.country`	`string`	ISO country code (e.g. `"US"`, `"JP"`)
`filters.price.min`	`number`	Minimum price, inclusive (text search only). A page may contain fewer than `limit` results
`filters.price.max`	`number`	Maximum price, inclusive (text search only)
`filters.price.currency`	`string`	Currency of the bounds (e.g. `"USD"`). Items in another currency are not filtered out; items with no price are kept under a max-only bound but never match a min
`filters.sortBy`	`"price-low-to-high" \| "price-high-to-low"`	Sort by price (text search only)
`filters.supportedOnly`	`boolean`	Only return products from merchants where checkout is supported (`coverage.checkout: "supported"` - see Merchants). Applied after the search runs, so a page may contain fewer than `limit` results
`filters.merchants`	`string[]`	Restrict a text search to these merchants (1–50), as hosts or URLs (e.g. `nike.com`). Entries that match no merchant are skipped; if none match, the request returns a 400. A page may contain fewer than `limit` results - page until `nextCursor` is null

Global search results are ordered by merchant checkout coverage: products from supported merchants rank first, then testing, then unsupported (the search engine’s order is preserved within each tier). Passing sortBy disables this ranking - an explicit price sort is kept as-is. To exclude non-supported merchants entirely, set filters.supportedOnly: true.

supportedOnly is a per-request filter on global search results, and is separate from your app’s Experimental merchants setting. Global search is never gated by that setting, so a testing merchant can appear in results even when your app may not transact with it - the merchant-scoped search, product details, or cart call is where the 403 surfaces. Setting supportedOnly: true keeps those merchants out of the results in the first place.

Parameter	Type	Description
`filters.merchant`	`string`	Required. Merchant name, host, or URL (e.g. `"nike.com"`)
`filters.country`	`string`	ISO country code - especially important for region-specific merchants (e.g. `"AU"` for priceline.com.au)
`filters.location`	`object`	`{ country, state, city, postalCode }`, most-general first; set at least one. Best-effort - honored by merchants whose results depend on location (currently `fandango.com`); ignored otherwise. `location.country` wins over `filters.country`
`filters.price.min`	`number`	Minimum price, inclusive
`filters.price.max`	`number`	Maximum price, inclusive
`filters.price.currency`	`string`	Currency of the bounds (e.g. `"USD"`). Items in another currency are not filtered out; items with no price are kept under a max-only bound but never match a min
`filters.sortBy`	`"price-low-to-high" \| "price-high-to-low"`	Sort results by price. Best-effort - honored only by merchants whose search method supports sorting; ignored otherwise
`filters.category`	`string`	Search within one category, from `searchFilters.category` on `merchants.retrieve`. Case-insensitive. Merchants with categories only - see Search one category
`filters.options`	`object`	Variant-option filters as name → value pairs (e.g. `{ "size": "M", "color": "black" }`). Accepts displayed values or merchant option codes - see below. Best-effort - honored for merchants served from Henry’s search index; ignored by live search methods
`filters.includeOutOfStock`	`boolean`	Keep sold-out products in the results. Default `false` - see below
`filters.imageUrl`	`string`	Search this merchant’s catalog by image instead of text. HTTP URL, data URL, or base64 payload. Available for merchants whose catalog Henry has prepared for image search; others return a `400` error. `query`, `sortBy` and `cursor` don’t apply

Sold-out products are dropped by default. Only the explicit cannot-buy states are dropped - out_of_stock and discontinued (the merchant no longer offers the product at all): products whose availability is unknown, and products that are limited_stock, preorder, or backorder, are always returned.Where the filter runs depends on the merchant. For merchants served from Henry’s search index it runs inside the query, so limit counts products you can actually buy. The Shopify catalog search methods apply it after the page is cut, so a page may contain fewer than limit results - page until nextCursor is null, not until a page comes back short. Best-effort: other live search methods return whatever the merchant lists.

filters.options values are case-insensitive and accept either the option value the merchant displays ("M", "29", "black") or the merchant’s own option code as returned by Product Details ("size-6000", "color-001") - both match the same products. Matching is product-level: a product matches when any of its variants carries the value, which may be a different variant than the one its link resolves to.

Don’t guess option names and values - discover them. merchants.retrieve returns a searchFilters field with the exact filter axes each merchant’s catalog supports. See Discover search filters.

Error handling

Error	Cause	Resolution
`401 Unauthorized`	Invalid API key	Check `HENRY_SDK_API_KEY`
`400 Bad Request`	Missing `query` or invalid filter values, a `category` the merchant doesn’t have (or on a merchant without categories), `category` combined with `filters.imageUrl`, or merchant image search on a merchant not prepared for it	Validate input before calling
`403 Forbidden`	Merchant search or product details for a merchant that isn’t `supported`, while your app has experimental merchants off	Enable Experimental merchants, or pick a supported merchant
`status: "failed"`	Job error - check `error` field	Log and retry

Next steps

Universal Cart

Use the product link to add items to a cart

Merchants

Browse supported merchants beforehand

Getting Started

Key Features

Async & Events

Agents

Info

Overview

Prerequisites

Search the catalog

Fetch product details

Affiliate links

Image search

Search one merchant by image

Sync mode

Merchant search

Search one category

Search parameters reference

Top-level parameters

Global search filters (`type: 'global'`)

Merchant search filters (`type: 'merchant'`)

Error handling

Next steps

Universal Cart

Merchants

​Overview

​Prerequisites

​Search the catalog

​Fetch product details

​Affiliate links

​Image search

​Search one merchant by image

​Sync mode

​Merchant search

​Search one category

​Search parameters reference

​Top-level parameters

​Global search filters (type: 'global')

​Merchant search filters (type: 'merchant')

​Error handling

​Next steps

Universal Cart

Merchants

Overview

Prerequisites

Search the catalog

Fetch product details

Affiliate links

Image search

Search one merchant by image

Sync mode

Merchant search

Search one category

Search parameters reference

Top-level parameters

Global search filters (`type: 'global'`)

Merchant search filters (`type: 'merchant'`)

Error handling

Next steps