Skip to main content

Live Example

​
Overview

Several Henry operations are async - they return immediately with a refId and a status, and results arrive once processing completes. You poll the corresponding poll* endpoint until status reaches a terminal state. Operations that follow this pattern:
OperationTriggerPoller
Product searchproducts.searchproducts.pollSearch
Product detailsproducts.detailsproducts.pollDetails
Headless checkoutcart.checkout.purchasecart.checkout.pollPurchase
Checkout detailscart.checkout.detailscart.checkout.pollDetails

​
Statuses

StatusTerminalAction
pendingNoKeep polling
processingNoKeep polling
complete✅Read result
failed✅Log error, investigate and retry

​
Sync mode - skip polling entirely

All async operations support mode: "sync", which blocks the request for up to 30 seconds until the operation completes. If the result is ready within that window, you get it in a single call with no polling needed. 
const search = await henry.products.search({
	type: 'global',
	filters: { type: 'text', query: 'Nike Air Max' },
	mode: 'sync',
});

// If completed within 30s, result is already populated
if (search.status === 'complete') {
	console.log(search.result?.products);
}
If the operation doesn’t complete within 30 seconds, sync mode returns with a non-terminal status (pending or processing) and you’ll need to fall back to polling. For operations that reliably take longer (e.g. headless checkout), prefer mode: "async" with the poll helper below.

​
Reusable poll helper

This generic helper works for any Henry async operation. Drop it in a shared utility file and import it wherever you need it. 
// utils/henry-poll.ts
export async function pollJob<T extends { status: string; refId: string }>(
	initial: T,
	poller: (args: { refId: string }) => Promise<T>,
	options: {
		intervalMs?: number;
		maxAttempts?: number;
	} = {},
): Promise<T> {
	const { intervalMs = 1000, maxAttempts = 60 } = options;

	let result = initial;
	let attempts = 0;

	while ((result.status === 'pending' || result.status === 'processing') && attempts < maxAttempts) {
		await new Promise((r) => setTimeout(r, intervalMs));
		result = await poller({ refId: initial.refId });
		attempts++;
	}

	if (result.status === 'pending' || result.status === 'processing') {
		throw new Error(`Henry request ${initial.refId} timed out after ${maxAttempts} attempts`);
	}

	return result;
}

​
Examples

import HenrySDK from '@henrylabs/sdk';
import { pollJob } from './utils/henry-poll';

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

const searchResult = await pollJob(
	await henry.products.search({
		type: 'global',
		filters: {
			type: 'text',
			query: 'Nike Air Max',
			sortBy: 'price-low-to-high',
		},
		limit: 20,
	}),
	(args) => henry.products.pollSearch(args),
);

if (searchResult.status !== 'complete') {
	throw new Error(`Search ${searchResult.status}: ${JSON.stringify(searchResult.error)}`);
}

const { products, pagination } = searchResult.result!;
console.log(`Found ${products.length} products`);

​
Product details

const detailResult = await pollJob(
	await henry.products.details({
		link: 'https://www.nike.com/t/air-max-270-shoes/AH8050-002',
	}),
	(args) => henry.products.pollDetails(args),
);

const product = detailResult.result;
console.log(product?.name, product?.price);

​
Headless checkout

Purchase is async too - Henry places the order with the merchant(s) in the background. 
const purchaseResult = await pollJob(
	await henry.cart.checkout.purchase('crt_sa2aEsCz9PRM', {
		buyer: {
			name: { firstName: 'Jane', lastName: 'Doe' },
			email: 'jane@example.com',
			phone: '+19175551234',
			shippingAddress: {
				line1: '350 5th Ave',
				city: 'New York',
				province: 'NY',
				postalCode: '10118',
				countryCode: 'US',
			},
			card: {
				nameOnCard: { firstName: 'Jane', lastName: 'Doe' },
				details: {
					cardToken: 'card_live_...',
				},
			},
		},
	}),
	(args) => henry.cart.checkout.pollPurchase(args),
	{ intervalMs: 2000, maxAttempts: 30 },
);

if (purchaseResult.status === 'complete') {
	const { total } = purchaseResult.result!.costs;
	console.log(`Order placed - total: ${total.value} ${total.currency}`);
}

​
Tips

The pollJob helper defaults to 1s intervals and 60 attempts, which works for most cases. Product search and details typically complete in 2–5 seconds; orders take longer since Henry places them with the merchant. For order fulfillment, consider skipping polling entirely - Webhooks let Henry push results to you instead.

​
Next steps

Webhooks

Skip polling for order events - have Henry push results to your server instead

Order Management

List and filter orders after checkout