Merchants

Overview

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

merchants.list - browse all merchants Henry lists publicly, 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 is unknown to Henry or isn’t publicly listed.

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 categories and 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?.category);
// → ["Men's Footwear", "Women's Apparel", "Accessories"] (Shopify merchants)

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.products.search({
	type: 'merchant',
	filters: {
		merchant: 'nike.com',
		category: "Men's Footwear",
		options: { size: 'M', color: 'Black' },
	},
});

category is listed for Shopify stores and zara.com. searchFilters is null until either is available - options refresh 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.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.

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;

Experimental merchants

A testing status means Henry is actively bringing that capability online but does not yet guarantee it. Each app decides whether it may use those merchants, with the Experimental merchants switch in Settings → App → General → Merchant coverage.

Switch	Which merchants your app may use
On	Search and details: any merchant. Checkout: `supported` and `testing` merchants, never `unsupported`
Off	Only merchants that are `supported` for the capability you are calling

With the switch off, a request whose merchant is not supported is rejected with a 403 naming the merchant and the capability. The status is checked per capability, so a merchant that is supported for product search and testing for checkout can be searched but not purchased from. The three gates are merchant-scoped products.search (product search), products.details (product details), and cart.create / cart.item.add / cart.item.update (checkout). The checkout gate runs again when the order is placed, so a cart built before the switch was turned off cannot be purchased either. Global product search is never gated — it spans the whole web, and its results are already ordered supported before testing before unsupported. Pass filters.supportedOnly when you only want merchants Henry fully supports. Every app has it on by default, so a new integration sees the whole catalog until its owner narrows it. Apps created before this setting existed keep exactly the behavior they already had.

Checkout is never allowed for a merchant that is unsupported for checkout, whatever the switch says: cart.create, cart.item.add, cart.item.update, and placing the order all return a 403.

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

Error handling

Error	Cause
`401 Unauthorized`	Invalid API key
`400 Bad Request`	Invalid `limit` or other malformed parameters
`404 Not Found`	`merchants.retrieve` called with an unknown or unlisted 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

Experimental merchants

Affiliate rates

Filter reference (`merchants.list`)

Error handling

Next steps

Product Discovery

Universal Cart

​Overview

​Prerequisites

​List merchants

​Retrieve a single merchant

​Search merchants

​Discover search filters

​Filter merchants

​Coverage

​Experimental merchants

​Affiliate rates

​Filter reference (merchants.list)

​Error handling

​Next steps

Product Discovery

Universal Cart

Overview

Prerequisites

List merchants

Retrieve a single merchant

Search merchants

Discover search filters

Filter merchants

Coverage

Experimental merchants

Affiliate rates

Filter reference (`merchants.list`)

Error handling

Next steps