Skip to main content

​
Overview

Use the Henry Shopping SDK to power search, product detail pages, and variant availability checks across any merchant on the internet. The SDK exposes normalized pricing, rich metadata, and optional variant validation so you can build immersive shopping experiences quickly.

​
Prerequisites

  • Henry API key from Sandbox or Production
  • @henrylabs/sdk installed in your backend or server runtime
  • Optional x-user-id value when you want to associate requests with an end user (pass via request options)
import HenrySDK from "@henrylabs/sdk";

export const client = new HenrySDK({
  apiKey: process.env.HENRY_API_KEY!,
  environment: "sandbox", // production or sandbox
});
1

Search the catalog

Start with client.products.search to retrieve items that match a keyword plus optional filters.
const search = await client.products.search({
  query: 'wireless earbuds',
  limit: 12,
  region: 'US',
  greaterThanPrice: 50,
  lowerThanPrice: 250,
  manufacturer: 'Sony',
});

const products = search.data;
const firstProduct = products[0];
Each result includes basic product metadata such as SKU ID, name, pricing, images, merchant name so you can render initial product cards.
2

Fetch enriched product details

When a shopper selects an item, call client.products.retrieveDetails with the productId from search. The response returns a product link, variants, reviews, SKU pricing, and additional images.
const detail = await client.products.retrieveDetails({
  productId: firstProduct.id,
});

const { productResults } = detail.data;
console.log(productResults.title, productResults.stores, productResults.variants);
The detail payload gives you everything you need to render a information rich product page, allowing users to compare variants, add to cart, and launch checkout.
3

Check variant availability (optional)

Need live stock info for a specific variant combination? Use the experimental client.products.variantCheck helpers. The create call returns a request ID you can poll with retrieveStatus.
const variantCheck = await client.products.variantCheck.create({
  product: {
    productId: firstProduct.id,
    name: firstProduct.name,
    price: String(firstProduct.price),
    quantity: 1,
    metadata: { color: 'Black', size: 'Small' },
    productLink: firstProduct.productLink,
  },
  'x-user-id': 'user_123',
});

const status = await client.products.variantCheck.retrieveStatus(variantCheck.requestId);

console.log(status.status, status.data?.stockStatus);
Status values include processing, completed, or timeout. When the request completes, data.stockStatus.available indicates whether the combination is in stock, and data.stockStatus.details surfaces per-attribute matches.
Variant checks are currently experimental. Expect the schema to evolve and add graceful fallbacks when the service returns failed or timeout.

​
Error handling

  • 401 Unauthorized — confirm the API key you passed to the client.
  • 404 Not Found — the product or variant request may have expired; rerun the search or create the variant check again.
  • Variant check polling can return timeout; prompt users to retry if that occurs.

​
Next steps

  • Persist the id returned from search so you can correlate cart adds.
  • Continue to Universal Cart to let shoppers save the products they discover.