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

# Orders

> Orders created from the current end user's baskets, with status and data updates

`Orders` creates an order from a [basket](/reference/sdk/baskets) and reads or updates the current end user's orders. An order carries the basket's `items` and `currency`, your own `data` fields (shipping, payment, notes), and platform-maintained `status`, `totalAmount`, and `itemCount`. Available wherever a current end user exists: tools, dynamic jobs, and trigger-fired turns (see [execution contexts](/concepts/execution-contexts)).

*Verified against lua-cli 3.33.0.*

```ts theme={null}
import { Orders, OrderStatus } from 'lua-cli';
```

## Quick example

```ts theme={null}
import { Orders, OrderStatus } from 'lua-cli';

const order = await Orders.create({ basketId: 'basket_abc123', data: { paymentMethod: 'stripe' } });
await order.updateStatus(OrderStatus.CONFIRMED);
await order.update({ trackingNumber: '1Z999AA10123456784' });
console.log(order.toJSON().id, order.status, order.trackingNumber);
```

## Methods

### create()

Creates an order from a basket's items.

```ts theme={null}
Orders.create(orderData: { basketId: string; data: Record<string, any> }): Promise<OrderInstance>
```

<ParamField path="orderData.basketId" type="string" required>The basket to convert.</ParamField>
<ParamField path="orderData.data" type="Record<string, any>" required>Your order fields, for example `shippingAddress`, `paymentMethod`, and `notes`.</ParamField>

The parameter is typed `any` in the SDK; the platform requires `basketId`.

**Returns** — the order as an [`OrderInstance`](#orderinstance) with `status` `pending`.

**Example**

```ts theme={null}
import { Orders } from 'lua-cli';

const order = await Orders.create({
  basketId: 'basket_abc123',
  data: { shippingAddress: { line1: '1 Main St', city: 'Oslo', postalCode: '0150', country: 'NO' }, paymentMethod: 'stripe' },
});
console.log(order.toJSON().id, Number(order.totalAmount).toFixed(2));
```

**Errors** — `Failed to create order`.

### updateStatus()

Sets an order's status. The status comes first.

```ts theme={null}
Orders.updateStatus(status: OrderStatus, orderId: string): Promise<OrderResponse>
```

<ParamField path="status" type="OrderStatus" required>One of the [`OrderStatus`](#orderstatus) values.</ParamField>
<ParamField path="orderId" type="string" required>The order's id.</ParamField>

**Returns**

<ResponseField name="order" type="OrderResponse">
  The raw order record, not an instance.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Order id.</ResponseField>
    <ResponseField name="orderId" type="string">The order's public identifier.</ResponseField>
    <ResponseField name="data" type="{ currency: string; items: BasketItem[]; createdAt: string; basketId: string; orderDate: string; orderId: string; [key: string]: any }">Contents and your fields.</ResponseField>
    <ResponseField name="common" type="{ status: string; totalAmount: string | number; currency: string; itemCount: number }">Platform-maintained totals and status.</ResponseField>
    <ResponseField name="createdAt, updatedAt" type="string">ISO 8601 timestamps.</ResponseField>
  </Expandable>
</ResponseField>

**Example**

```ts theme={null}
import { Orders, OrderStatus } from 'lua-cli';

const updated = await Orders.updateStatus(OrderStatus.FULFILLED, 'order_def456');
console.log(updated.common.status);
```

**Errors** — `Failed to update order status`.

### updateData()

Merges fields into an order's `data`. The data comes first.

```ts theme={null}
Orders.updateData(data: Record<string, any>, orderId: string): Promise<OrderResponse>
```

<ParamField path="data" type="Record<string, any>" required>Fields to add or replace.</ParamField>
<ParamField path="orderId" type="string" required>The order's id.</ParamField>

**Returns** — the raw order record, as `updateStatus()`.

**Example**

```ts theme={null}
import { Orders } from 'lua-cli';

await Orders.updateData({ trackingNumber: '1Z999AA10123456784', carrier: 'UPS' }, 'order_def456');
```

**Errors** — `Failed to update order data`.

### get()

Returns the current end user's orders, optionally filtered by status.

```ts theme={null}
Orders.get(status?: OrderStatus): Promise<OrderInstance[]>
```

<ParamField path="status" type="OrderStatus">Omit it for every order.</ParamField>

**Returns** — an array of [`OrderInstance`](#orderinstance).

**Example**

```ts theme={null}
import { Orders, OrderStatus } from 'lua-cli';

const pending = await Orders.get(OrderStatus.PENDING);
const revenue = pending.reduce((sum, order) => sum + Number(order.totalAmount), 0);
```

**Errors** — `Failed to get user orders`.

### getById()

Returns one order by id.

```ts theme={null}
Orders.getById(orderId: string): Promise<OrderInstance>
```

**Returns** — the order as an [`OrderInstance`](#orderinstance). An unknown id throws; there is no `null` return.

**Example**

```ts theme={null}
import { Orders } from 'lua-cli';

const order = await Orders.getById('order_def456');
console.log(order.status, order.items, order.shippingAddress);
```

**Errors** — `Failed to get order`.

## OrderInstance

The object `create()`, `get()`, `getById()`, and [`Baskets.placeOrder()`](/reference/sdk/baskets#placeorder) return. Every order field is readable directly through the instance's proxy: `status`, `totalAmount`, `itemCount`, and `currency` from the platform, `items`, `basketId`, `orderDate`, `createdAt`, and your own `data` fields. Direct assignments stay local until `save()`.

The identity fields `id`, `orderId`, `userId`, and `agentId` and the raw `data` and `common` objects are private in the type declarations, so `order.id` doesn't compile. Read the id from `order.toJSON().id`. `totalAmount` is typed `string | number`; wrap it in `Number()` before arithmetic.

### updateStatus()

Sets the status and refreshes the instance's platform fields.

```ts theme={null}
order.updateStatus(status: OrderStatus): Promise<any>
```

**Returns** — the order's fields, `{ ...data, ...common, id }`.

### update()

Merges fields into `data` on the server and refreshes the instance.

```ts theme={null}
order.update(data: Record<string, any>): Promise<any>
```

**Returns** — the order's fields, `{ ...data, ...common, id }`.

### save()

Writes the whole local `data` to the server.

```ts theme={null}
order.save(): Promise<boolean>
```

**Returns** — `true`.

**Example**

```ts theme={null}
import { Orders } from 'lua-cli';

const order = await Orders.getById('order_def456');
order.carrier = 'UPS';
order.estimatedDelivery = '2026-09-20';
await order.save();
```

**Errors** — `Failed to save order data`.

### toJSON()

Returns `{ ...data, ...common, id }`, which is what `JSON.stringify(order)` and `console.log(order)` print.

## Types

### OrderStatus

| Member                  | Value       | Meaning                                        |
| ----------------------- | ----------- | ---------------------------------------------- |
| `OrderStatus.PENDING`   | `pending`   | Created, not yet confirmed; the initial status |
| `OrderStatus.CONFIRMED` | `confirmed` | Confirmed and being processed                  |
| `OrderStatus.FULFILLED` | `fulfilled` | Completed                                      |
| `OrderStatus.CANCELLED` | `cancelled` | Cancelled                                      |

`OrderInstance` and `OrderStatus` are exported. `OrderResponse` is not; name it from `Orders.updateStatus`.

```ts theme={null}
import { Orders, OrderStatus } from 'lua-cli';

type OrderRecord = Awaited<ReturnType<typeof Orders.updateStatus>>;

export function isOpen(order: OrderRecord): boolean {
  return order.common.status === OrderStatus.PENDING || order.common.status === OrderStatus.CONFIRMED;
}
```

## See also

* [`Baskets`](/reference/sdk/baskets) — where orders come from
* [`Products`](/reference/sdk/products) — the catalog
* [Send proactive messages](/build/send-proactive-messages) — notify the end user when a status changes
* [Commerce REST API](/reference/rest/commerce) — orders over HTTP