> ## 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.
# Core Concepts
> Understand async jobs, cart lifecycle, checkout modes, and order states before you build
## The shopping flow
Henry's features are **modular** - use just the ones you need. You can call `cart.checkout.purchase` with a product link directly, use `products.details` without ever touching the cart, or run the full pipeline end-to-end:
```mermaid theme={null}
flowchart TD
A["๐ Product Discovery
search ยท details"] --> B["๐ Universal Cart
create ยท add ยท update ยท remove"]
B --> C{Checkout mode?}
C -->|Hosted| D["๐ Hosted Checkout
'checkoutUrl' โ Henry modal"]
C -->|Headless| E["โก Headless Checkout
'cart.checkout.purchase'
full UI control"]
D --> F["๐ฆ Order
pending โ processing โ complete"]
E --> F
```
***
## Async jobs
Product search, product details, and checkout details are **async operations**. When you call them, Henry immediately returns a `refId` and a `status`.
You have three options for handling async results:
1. **Sync mode** - pass `mode: "sync"` and the request blocks for up to 30 seconds until the result is ready. Simplest approach for fast operations.
2. **Poll** - use the corresponding `poll*` method until `status` becomes `complete` (or `failed`).
3. **Webhooks** - have Henry push the result to your server when it's ready.
**Statuses:**
| Status | Meaning |
| ------------ | ------------------------------------------ |
| `pending` | Queued, not started yet |
| `processing` | Actively running |
| `complete` | Results are ready in `result` |
| `failed` | Hit an unrecoverable error - check `error` |
See [Polling](/v1/sdk/server/guides/polling) for a reusable helper and retry strategies, or [Webhooks](/v1/sdk/server/guides/webhooks) to have Henry send results to you instead.
***
## Cart lifecycle
Create a cart with one or more product links. From there you can add, update, or remove items freely. When ready, send the buyer to checkout.
Items are identified by their product URL - no separate product ID needed. `cart.create` returns a `checkoutUrl` immediately, so there's no extra step to set up hosted checkout.
***
## Checkout modes
Henry collects shipping, payment, and taxes via a hosted modal.
Submit payment and shipping directly from your server. Full UI control.
***
## Order states
After checkout (either mode), Henry creates an order and processes it asynchronously across one or more merchants.
```mermaid theme={null}
stateDiagram-v2
[*] --> pending : Order created
pending --> processing : Payment accepted
processing --> complete : All items placed
processing --> cancelled : Payment failed
complete --> [*]
cancelled --> [*]
```
| Status | Description |
| ------------ | ----------------------------------------------------------- |
| `pending` | Order received, payment not yet confirmed |
| `processing` | Payment confirmed, placing items with merchants |
| `complete` | All items successfully placed - `result.costs` is populated |
| `cancelled` | Order could not be completed |
Use `orders.list({ cartId })` to fetch orders associated with a specific cart, or omit `cartId` to list all orders for your app.
***
## Merchants
Every product `link` is associated with a merchant `host` (e.g. `nike.com`). You can browse supported merchants with `merchants.list` - useful for building merchant-selection filters before adding them to a cart.
***
## Monetization
Every completed order generates a commission for your application. Henry handles payout calculations, merchant relationships, and reporting. You configure commission amounts (fixed + percent) in the `settings` object when creating a cart.
```typescript theme={null}
await henry.cart.create({
items: [...],
settings: {
commissionFeePercent: 5, // 5% of order total
commissionFeeFixed: { value: 1.99, currency: 'USD' }, // + $1.99 flat
},
});
```