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
  },
  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..." "pending"

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
  mode: 'async',          // or 'sync' to wait up to 30s for results
});

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

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 with availability
  featuredImage: product?.images?.find(i => i.isFeatured)?.url,
});

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

Image search

Search by image instead of text. Pass a URL, data URL, or base64 payload to find visually similar products.

// 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,
});

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' },
	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 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

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 filter (text search only)
`filters.price.max`	`number`	Maximum price filter (text search only)
`filters.price.currency`	`string`	Currency for price filter (e.g. `"USD"`)
`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 (`coverageStatus: "supported"` - see Merchants). Applied after the search runs, so a page may contain fewer than `limit` results

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.

Parameter	Type	Description
`filters.merchant`	`string`	Required. Merchant name, host, or URL (e.g. `"nike.com"`)
`filters.price.min`	`number`	Minimum price filter
`filters.price.max`	`number`	Maximum price filter
`filters.price.currency`	`string`	Currency for price filter

Error handling

Error	Cause	Resolution
`401 Unauthorized`	Invalid API key	Check `HENRY_SDK_API_KEY`
`400 Bad Request`	Missing `query` or invalid filter values	Validate input before calling
`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

Image search

Sync mode

Merchant search

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

​Image search

​Sync mode

​Merchant search

​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

Image search

Sync mode

Merchant search

Search parameters reference

Top-level parameters

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

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

Error handling

Next steps