Skip to main content

​
Overview

This guide walks you through building a complete purchase flow with the Henry Shopping SDK. You’ll search the catalog, show product details, add items to a cart, launch hosted checkout, and monitor the resulting order.
Want to see it in action? Check out our Live Demo — a fully functional Next.js app that you can clone and run locally.

​
Prerequisites

  • Henry API key from the Henry Dashboard
  • Node.js 18+ (or Bun/Deno with npm compatibility)
  • A server-side environment where you can keep your API key private

​
Setup

Install the SDK with your preferred package manager: 
pnpm add @henrylabs/sdk
Store your credentials in environment variables: 
# .env.local
HENRY_API_KEY=your_api_key_here
Never expose your API key in client-side code. Proxy SDK calls through your backend just like the demo app.

​
Step 1: Initialize the client

import HenrySDK from "@henrylabs/sdk";

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

​
Step 2: Search for products

const search = await client.products.search({
  query: "nike shoes",
});

const firstProduct = search.data[0];
Each search result includes identifiers, imagery, pricing, and merchant metadata you can surface directly in your UI.

​
Step 3: Get product details

const detail = await client.products.retrieveDetails({
  productId: firstProduct.id,
});

const product = detail.data.productResults;
The detail payload enriches the search result with thumbnails, variant options, merchant pricing, and review summaries.

​
Step 4: Add to the universal cart

const userId = "user_123";

const cart = await client.cart.items.add({
  "x-user-id": userId,
  productsDetails: [
    {
      productId: firstProduct.id,
      name: firstProduct.name,
      price: String(firstProduct.price),
      quantity: 1,
      productLink: firstProduct.productLink,
      productImageLink: firstProduct.imageUrl,
      metadata: {
        Size: "10",
        Color: "Black",
      },
    },
  ],
});

console.log(cart.data.cart_summary);
The SDK automatically creates the cart if it doesn’t exist and keeps returning updated summaries as you add or remove items.

​
Step 5: Generate a hosted checkout

const checkout = await client.cart.createCheckout({ "x-user-id": userId });

const checkoutUrl = checkout.data.checkout_url;
// Redirect the shopper, open an iframe, or launch a modal with this URL
// Capture the emitted orderId once the hosted flow reports order completion
Hosted checkout collects shipping details, payments, taxes, and confirmation in one responsive flow. Prefer a custom experience? Jump to Headless Checkout after you finish this quickstart.

​
Step 6: Track the resulting order

const orderId = "order_123"; // returned from the hosted checkout completion event
const order = await client.orders.retrieveStatus(orderId);

console.log(order.data.status, order.data.statusMessage);
Use polling or background jobs to keep your application in sync until the order reaches a terminal state such as delivered, cancelled, or failed.

​
Next steps

Run the Demo

See how the Henry Shopping SDK powers a full-stack checkout experience.

Product Discovery

Deep dive into search, details, and variant checks.

Universal Cart

Manage carts, variant checks, and quantity updates.

Cart Checkout

Compare hosted and headless checkout flows.