# order (https://docs.salla.dev/twilight/react/api/modules/order)



Use `order` for the account order list, a single order page and the thank-you page after checkout. Orders belong to the signed-in customer, so gate calls with `useUser().isLoggedIn`.

```tsx title="app/components/MyOrders.tsx"
import { useQuery } from '@tanstack/react-query';
import { useUser } from '@salla.sa/twilight-theme-engine/hooks/useUser';
import { order } from '@salla.sa/twilight-theme-engine/api/order';

export function MyOrders() {
  const { isLoggedIn } = useUser();
  const { data } = useQuery({
    ...order.queries.list({ with_items: true }),
    enabled: isLoggedIn,
  });
  const orders = data?.data ?? [];

  return <p>{orders.length} orders</p>;
}
```

```ts title="app/routes/account.orders.tsx"
import { order } from '@salla.sa/twilight-theme-engine/api/order';
import { getTwilightContext } from '@salla.sa/twilight-theme-engine/tanstack';

loader: () => {
  const { queryClient } = getTwilightContext();
  return queryClient.fetchQuery(order.queries.list({ status: 'completed' }));
},
```

## Methods [#methods]

| Method            | Parameters                  | Returns                                                   | Request                                                      | Login needed              |
| ----------------- | --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------ | ------------------------- |
| `list`            | `params?: OrdersListParams` | `Promise<{ data: OrderListItem[]; cursor?: Pagination }>` | `GET orders?page&cursor&status&feedback_status&with_items=1` | Yes                       |
| `find`            | `id: string`                | `Promise<{ order: Order }>`                               | `GET orders/{id}`                                            | Yes                       |
| `findOrThrow`     | `id: string`                | `Promise<{ order: Order }>`                               | Same as `find`                                               | Yes                       |
| `shipments`       | `orderId: string`           | `Promise<OrderShipmentItem[]>`                            | `GET orders/{orderId}/shipments`                             | Yes                       |
| `ratings`         | `orderId: string`           | `Promise<OrderRatingItem[]>`                              | `GET orders/{orderId}/ratings`                               | Yes                       |
| `thankYou`        | `orderId: string`           | `Promise<CheckoutThankYouData>`                           | `GET checkout/thank-you/{orderId}`                           | Not checked by the module |
| `thankYouOrThrow` | `orderId: string`           | `Promise<CheckoutThankYouData>`                           | Same as `thankYou`                                           | Not checked by the module |

`OrdersListParams`: `page`, `cursor`, `status`, `feedback_status`, `with_items` (adds each order's items) and `signal`. "Login needed" means the API wants the customer's token; the module does not check it for you.

## Queries [#queries]

| Query                              | Key                                |
| ---------------------------------- | ---------------------------------- |
| `order.queries.list(params?)`      | `['orders', 'list', params]`       |
| `order.queries.find(id)`           | `['orders', 'detail', id]`         |
| `order.queries.shipments(orderId)` | `['orders', 'shipments', orderId]` |
| `order.queries.ratings(orderId)`   | `['orders', 'ratings', orderId]`   |
| `order.queries.thankYou(orderId)`  | `['orders', 'thankYou', orderId]`  |

No key includes the locale, the scope or the customer. The token is what separates customers, so clear `['orders']` on logout so the next customer does not see cached data.

## Gotchas [#gotchas]

* Guests get an error from the API (`token_not_provided`). Skip the call with `isLoggedIn`.
* `list` turns a `null` `data` into `[]`; `cursor` may be absent. Pass `cursor.next` back as `cursor`.
* `findOrThrow` turns a 401 or 403 into the unauthorized page and a 404 or 410 (an order the customer cannot see) into the not-found page, and lets other errors through. A guest's 400 `token_not_provided` is neither, so it still reaches the error boundary. `thankYouOrThrow` turns a 404 or 410 into not-found. See [Errors](https://docs.salla.dev/twilight/react/api/errors-timeouts-and-retries).
* `shipments` and `ratings` return `[]` when the response has no `data`.
* Orders are read-only here. Invalidate `['orders']` after an SDK action that changes one, such as a rating or a cancel.

## See also [#see-also]

* [Account orders route](https://docs.salla.dev/twilight/react/routes/account-orders) and [Account order route](https://docs.salla.dev/twilight/react/routes/account-order)
* [Thank-you route](https://docs.salla.dev/twilight/react/routes/thank-you)
* [user](https://docs.salla.dev/twilight/react/api/modules/user)