Skip to main content

​
Overview

Use the Product Discovery APIs to power search, product detail pages, and inventory checks across any merchant on the internet. The endpoints expose normalized pricing, rich metadata, and optional variant validation so you can build immersive shopping experiences quickly.

​
Prerequisites

  • Henry Shopping API key from Sandbox or Production
  • Sandbox or production base URL (https://api.sandbox.henrylabs.ai/v0 during development)
  • Optional x-user-id header when you want to match requests to an end user
1

Search the catalog

Start with POST /products/search to retrieve items that match a keyword plus optional filters.
const response = await fetch("https://api.sandbox.henrylabs.ai/v0/products/search", {
  method: "POST",
  headers: {
    "x-api-key": process.env.HENRY_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "wireless earbuds",
    limit: 12,
    region: "US",
    greaterThanPrice: 50,
    lowerThanPrice: 250,
    manufacturer: "Sony"
  })
});

const { data: products } = await response.json();
const firstProduct = products[0];
Every product in the response includes id, name, price, currency, imageUrl, productLink, and the merchant source, so you can render tiles immediately.
2

Fetch enriched product details

When the shopper selects an item, call GET /products/details with the productId you received from search. This returns reviews, variant metadata, merchant pricing, and imagery.
const detail = await fetch(
  `https://api.sandbox.henrylabs.ai/v0/products/details?productId=${encodeURIComponent(firstProduct.id)}`,
  {
    headers: { "x-api-key": process.env.HENRY_API_KEY }
  }
);

const { data } = await detail.json();
const { productResults } = data;
console.log(productResults.title, productResults.stores, productResults.variants);
The detail payload mirrors the OpenAPI schema: thumbnails, merchant stores with pricing and shipping, shopper userReviews, and structured variants that list each selectable attribute.
3

Check variant availability (optional)

If you need real-time stock info for a specific variant combination, use POST /products/variant-check. The endpoint is marked experimental and returns a requestId you can poll.
const variantRequest = await fetch(
  "https://api.sandbox.henrylabs.ai/v0/products/variant-check",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.HENRY_API_KEY,
      "Content-Type": "application/json",
      "x-user-id": "user_123" // optional for tracking
    },
    body: JSON.stringify({
      product: {
        productId: firstProduct.id,
        name: firstProduct.name,
        price: String(firstProduct.price),
        quantity: 1,
        metadata: { color: "Black", size: "Small" },
        productLink: firstProduct.productLink
      }
    })
  }
);

const { requestId } = await variantRequest.json();

const status = await fetch(
  `https://api.sandbox.henrylabs.ai/v0/products/variant-check/${requestId}`,
  { headers: { "x-api-key": process.env.HENRY_API_KEY } }
);

const variantResult = await status.json();
console.log(variantResult.status, variantResult.data?.stockStatus);
You will receive status values like 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

  • 400 Bad Request — validate that required fields like query or productId are present and non-empty.
  • 401 Unauthorized — check the x-api-key header; sandbox and production keys are scoped separately.
  • 404 Not Found — the product or variant request may have expired; replay the initial call.

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