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: 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.

// 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',
		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 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, inclusive (text search only). Enforced on every price Henry can compare, so a page may contain fewer than `limit` results
`filters.price.max`	`number`	Maximum price filter, inclusive (text search only). Enforced on every price Henry can compare, so a page may contain fewer than `limit` results
`filters.price.currency`	`string`	Currency the bounds are denominated in (e.g. `"USD"`). An item priced in another currency is returned rather than dropped. An unresolved price is returned under a maximum-only bound but cannot satisfy a minimum
`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.country`	`string`	ISO country code - especially important for region-specific merchants (e.g. `"AU"` for priceline.com.au)
`filters.price.min`	`number`	Minimum price filter, inclusive. Forwarded to the merchant’s own price filter where its search method has one, and enforced on every price Henry can compare regardless of merchant, so a page may contain fewer than `limit` results
`filters.price.max`	`number`	Maximum price filter, inclusive. Same enforcement as `min`
`filters.price.currency`	`string`	Currency the bounds are denominated in. An item priced in another currency is returned rather than dropped. An unresolved price is returned under a maximum-only bound but cannot satisfy a minimum
`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.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

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	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

Affiliate links

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

​Affiliate links

​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

Affiliate links

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