Order Management

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_SDK_API_KEY!,
});

List orders

orders.list returns all orders for your application, newest first. It supports filtering by status and cart.

const { data: orders } = await henry.orders.list({
	limit: 20,
});

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

Filter by status

An order is pending or processing while it’s being purchased, then settles:

Status	Meaning
`complete`	Every item was purchased
`partially_complete`	Some items were purchased; check each `products[].status`
`failed`	No items were purchased; `error` says why
`cancelled`	The order was cancelled

// Only orders where every item was purchased
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: 'crt_sa2aEsCz9PRM',
});

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

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

Status	What it means	Terminal?
`pending`	Payment not yet confirmed	No
`processing`	Payment accepted, placing items with merchants — or an item failed and the order has not settled yet (up to an hour); that item reads `processing` too, and `result` is withheld	No
`complete`	Every item was purchased. `result.costs` is populated	✅
`partially_complete`	Some items were purchased, the rest failed — check each `products[].status`. `result.costs` covers the purchased items	✅
`failed`	No items were purchased — `error` has details	✅
`cancelled`	The order was cancelled at any stage — `error` has details	✅

Filter reference

Parameter	Type	Default	Description
`limit`	`number`	`20`	Results per page (1–100)
`cursor`	`string`	-	ISO-8601 timestamp - returns only orders created before it (newest first)
`status`	`"pending" \| "processing" \| "complete" \| "partially_complete" \| "failed" \| "cancelled"`	-	Filter by order status
`cartId`	`string`	-	Return only orders from this cart

Error handling

Error	Cause
`401 Unauthorized`	Invalid API key
`400 Bad Request`	Invalid `cartId` format or out-of-range `limit`
Empty `data` array	No orders found matching the filters
`status: "cancelled"`	Check `order.error` for the failure reason

Getting Started

Key Features

Async & Events

Agents

Info

Overview

Prerequisites

List orders

Filter by status

Filter by cart

Track order updates

Order statuses explained

Filter reference

Error handling

Next steps

Checkout

Universal Cart

​Overview

​Prerequisites

​List orders

​Filter by status

​Filter by cart

​Track order updates

​Order statuses explained

​Filter reference

​Error handling

​Next steps

Checkout

Universal Cart

Overview

Prerequisites

List orders

Filter by status

Filter by cart

Track order updates

Order statuses explained

Filter reference

Error handling

Next steps