Merchants

Overview

Every product link belongs to a merchant host (e.g. nike.com). The merchants resource lets you:

merchants.list - browse all merchants enabled for your application, with filters
merchants.search - free-text merchant search over name + host (typeahead-grade)
merchants.retrieve - fetch a single merchant by host

Each merchant comes with its per-method coverage statuses (checkout, productDetails, productSearch) - so you can pick the right merchants for your catalog and gate features per capability.

Prerequisites

import HenrySDK from '@henrylabs/sdk';

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

List merchants

Call merchants.list to retrieve all merchants available to your app.

const { data: merchants } = await henry.merchants.list({
	limit: 40,
});

for (const merchant of merchants) {
	console.log(merchant.name, merchant.host, merchant.coverage.checkout);
	// → "Nike" "nike.com" "supported"
}

Retrieve a single merchant

When you already know the host, merchants.retrieve fetches that merchant directly - no filtering, no pagination.

const { data: nike } = await henry.merchants.retrieve('nike.com');

console.log(nike.name, nike.coverage.checkout);
// → "Nike" "supported"

Returns 404 Not Found if the host isn’t enabled for your app.

Search merchants

When all you have is what a user typed - a name fragment, a host fragment - merchants.search resolves it to ranked merchants. It partial-matches the query against merchant name and host (case- and accent-insensitive), ranking prefix matches first, and returns a single ranked page.

const { data: matches } = await henry.merchants.search({
	q: 'nike',
	limit: 5,
});

console.log(matches.map(m => `${m.name} (${m.host})`));
// → ["Nike (nike.com)", ...]

Each result carries the full merchant payload - including per-method coverage - so you can scope a product search to a result’s host or gate checkout affordances without a second lookup.

Parameter	Type	Default	Description
`q`	`string`	-	Free-text query matched against name + host
`limit`	`number`	`10`	Maximum results (1–50)

Search is built for typeaheads: results are one ranked page with no cursor. Narrow the query instead of paging.

merchants.retrieve also returns searchFilters - the variant-option filter axes (option name → display values) that merchant-scoped product search accepts for this merchant.

const { data: merchant } = await henry.merchants.retrieve('nike.com');

console.log(merchant.searchFilters?.options);
// → { size: ["XS", "S", "M", "L"], color: ["Black", "White"] }

// Pass any discovered value straight into a merchant search:
const search = await henry.product.search({
	type: 'merchant',
	filters: {
		merchant: 'nike.com',
		options: { size: 'M', color: 'Black' },
	},
});

searchFilters is null until the merchant’s catalog has been indexed - its summary refreshes with the weekly catalog sync. Matching is case-insensitive and best-effort: option filters are honored for merchants served from Henry’s search index and ignored by live search methods.

Filter merchants

Filter by host

Look up a specific merchant by domain:

const { data } = await henry.merchants.list({
  host: 'nike.com',
});

const nike = data[0];
console.log(nike.name, nike.description);
console.log(nike.categories);   // ["fashion_and_accessories", "sports_and_outdoor"]
console.log(nike.website.urls); // [{ value: "https://nike.com", type: "landing" }]
console.log(nike.logo.urls);    // [{ value: "https://..." }]

If you already know the host, prefer merchants.retrieve - it’s a direct lookup instead of a filtered list.

Filter by name

Partial-match search on merchant display name:

const { data } = await henry.merchants.list({
  name: 'nike', // case-insensitive partial match
});

Filter by coverage

Restrict results to merchants Henry actively supports (vs. still being onboarded), per method:

// Merchants where checkout purchases are supported
const { data } = await henry.merchants.list({
  checkoutCoverage: 'supported',
  limit: 100,
});

// Filters combine: searchable AND checkout-supported
const { data: searchable } = await henry.merchants.list({
  productSearchCoverage: 'supported',
  checkoutCoverage: 'supported',
  limit: 100,
});

One filter per method: checkoutCoverage, productDetailsCoverage, productSearchCoverage.

coverageStatus is a deprecated alias of checkoutCoverage and is ignored when checkoutCoverage is also provided.

Filter by category

Find all merchants in one or more categories:

const { data } = await henry.merchants.list({
  categories: ['fashion_and_accessories', 'sports_and_outdoor'],
  limit: 100,
});

console.log(data.map(m => m.name));
// → ["Nike", "Adidas", "New Balance", ...]

Coverage

Every merchant record includes per-method coverage statuses. Use them to gate features per-merchant and pick the right merchants for each capability.

const { data: nike } = await henry.merchants.retrieve('nike.com');

// Per-method coverage: "supported" | "testing" | "unsupported"
nike.coverage.checkout;        // checkout purchases
nike.coverage.productDetails;  // product detail lookups
nike.coverage.productSearch;   // merchant-scoped product search

// Deprecated alias of coverage.checkout - always the same value
nike.coverageStatus;

Affiliate rates

When one of Henry’s affiliate networks covers a merchant, the record includes an affiliate object with the highest commission rate our coverage pays there — as a percentage of order value (6 means 6%). Use it to decide which merchants to promote.

const { data: nike } = await henry.merchants.retrieve('nike.com');

nike.affiliate?.maxCommissionRate; // e.g. 6 — or undefined when not covered

The object is omitted for merchants without affiliate coverage (or with no rate on file), so treat it as optional.

Filter reference (`merchants.list`)

Parameter	Type	Default	Description
`limit`	`number`	`20`	Results per page (1–100)
`cursor`	`string`	-	Pagination cursor from previous response
`host`	`string`	-	Exact domain match (e.g. `"nike.com"`)
`name`	`string`	-	Partial name match (e.g. `"nike"`)
`checkoutCoverage`	`string`	-	Checkout coverage: `supported`, `testing`, or `unsupported`
`productDetailsCoverage`	`string`	-	Product-details coverage: `supported`, `testing`, or `unsupported`
`productSearchCoverage`	`string`	-	Product-search coverage: `supported`, `testing`, or `unsupported`
`coverageStatus`	`string`	-	Deprecated. Alias of `checkoutCoverage`; ignored when both are sent
`categories`	`string[]`	-	Filter by one or more merchant categories

Available categories

automotive, baby_and_kids, ecommerce, electronics_and_gadgets, fashion_and_accessories, finance, food, health_and_beauty, home_and_living, lifestyle_and_entertainment, other, sports_and_outdoor, travel, education

Error handling

Error	Cause
`401 Unauthorized`	Invalid API key
`400 Bad Request`	Invalid `limit` or malformed `categories`
`404 Not Found`	`merchants.retrieve` called with an unknown / disabled host
Empty `data` array	No merchants match the filters (`merchants.list`)

Next steps

Product Discovery

Search products from a specific merchant using the merchant filter

Universal Cart

Add product links from supported merchants to a cart

Getting Started

Key Features

Async & Events

Agents

Info

Overview

Prerequisites

List merchants

Retrieve a single merchant

Search merchants

Discover search filters

Filter merchants

Coverage

Affiliate rates

Filter reference (`merchants.list`)

Available categories

Error handling

Next steps

Product Discovery

Universal Cart

​Overview

​Prerequisites

​List merchants

​Retrieve a single merchant

​Search merchants

​Discover search filters

​Filter merchants

​Coverage

​Affiliate rates

​Filter reference (merchants.list)

​Available categories

​Error handling

​Next steps

Product Discovery

Universal Cart

Overview

Prerequisites

List merchants

Retrieve a single merchant

Search merchants

Discover search filters

Filter merchants

Coverage

Affiliate rates

Filter reference (`merchants.list`)

Available categories

Error handling

Next steps