Skip to main content

Live Example

​
Overview

After a checkout completes (hosted or headless), Henry creates an order and orchestrates fulfillment across one or more merchants. Use orders.list to fetch, filter, and monitor those orders from your backend.

​
Prerequisites

import HenrySDK from '@henrylabs/sdk';

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

​
List orders

orders.list returns all orders for your application, newest first. It supports filtering and cursor-based pagination. 
const { data: orders } = await henry.orders.list({
	limit: 20,
});

for (const order of orders) {
	console.log(order.refId, order.status);
}

​
Filter by status

// Only completed orders
const { data: completed } = await henry.orders.list({
	status: 'complete',
	limit: 50,
});

​
Filter by cart

Look up the order(s) tied to a specific cart: 
const { data: orders } = await henry.orders.list({
	cartId: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
});

const order = orders[0];
console.log(order.status); // "complete"
console.log(order.result?.costs.total); // { amount: "149.99", currency: "USD" }

​
Paginate through results

let cursor: string | undefined;
let allOrders = [];

do {
	const { data: page, ...rest } = await henry.orders.list({
		limit: 40,
		cursor,
	});
	allOrders.push(...page);
	cursor = undefined; // update when pagination is available in response
} while (cursor);

​
Track order updates

Orders move through states asynchronously. You have two options:
  • Poll for status - query orders.list (filtered by cartId) on an interval until the order reaches a terminal state.
  • Receive a webhook - use settings.events on cart.create to fire a webhook when the order completes, avoiding polling entirely. See Universal Cart - Cart events.

​
Order statuses explained

StatusWhat it meansTerminal?
pendingPayment not yet confirmedNo
processingPayment accepted, placing items with merchantsNo
completeEvery item has concluded its purchase attempt - some may have succeeded, others may have failed. Check each item’s status individually. result.costs is populated.✅
cancelledThe order was cancelled at any stage - error field has details✅

​
Filter reference

ParameterTypeDefaultDescription
limitnumber20Results per page (1–100)
cursorstring-Pagination cursor from previous response
status"pending" | "processing" | "complete" | "cancelled"-Filter by order status
cartIdstring (UUID)-Return only orders from this cart

​
Error handling

ErrorCause
401 UnauthorizedInvalid API key
400 Bad RequestInvalid cartId format or out-of-range limit
Empty data arrayNo orders found matching the filters
status: "cancelled"Check order.error for the failure reason

​
Next steps

Checkout

Review both hosted and headless checkout flows

Universal Cart

Understand cart creation and item management