> ## Documentation Index
> Fetch the complete documentation index at: https://docs.henrylabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Management

> List, filter, and track orders - from pending payment to completed fulfillment

## 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

```typescript theme={null}
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 and cursor-based pagination.

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

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

### Filter by status

```typescript theme={null}
// 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:

```typescript theme={null}
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); // { value: 149.99, currency: "USD" }
```

### Paginate through results

```typescript theme={null}
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](/v1/sdk/server/guides/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                                                                                                                       | No        |
| `complete`   | Every item has concluded its purchase attempt - some may have succeeded, others may have failed. Check each item's status individually. `result.costs` is populated. | ✅         |
| `cancelled`  | The order was cancelled at any stage - `error` field has details                                                                                                     | ✅         |

***

## Filter reference

| Parameter | Type                                                     | Default | Description                              |
| --------- | -------------------------------------------------------- | ------- | ---------------------------------------- |
| `limit`   | `number`                                                 | `20`    | Results per page (1–100)                 |
| `cursor`  | `string`                                                 | -       | Pagination cursor from previous response |
| `status`  | `"pending" \| "processing" \| "complete" \| "cancelled"` | -       | Filter by order status                   |
| `cartId`  | `string` (UUID)                                          | -       | 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      |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Checkout" icon="credit-card" href="/v1/sdk/server/guides/checkout">
    Review both hosted and headless checkout flows
  </Card>

  <Card title="Universal Cart" icon="cart-shopping" href="/v1/sdk/server/guides/universal-cart">
    Understand cart creation and item management
  </Card>
</CardGroup>