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

# Orders

> Read the orders placed through your shop widgets.

An **order** is a completed purchase through an e-commerce widget (or a
catalog/collection checkout). Orders are read-only in v1.

## The order object

```json theme={null}
{
  "id": 3001,
  "ecommerceWidgetId": 77,
  "collectionId": null,
  "customerName": "Jane Doe",
  "customerEmail": "jane@example.com",
  "customerPhone": null,
  "amountCents": 2500,
  "currency": "usd",
  "status": "paid",
  "shippingAddress": null,
  "trackingNumber": null,
  "trackingCarrier": null,
  "shippedAt": null,
  "createdAt": "2026-05-20T09:30:00.000Z"
}
```

`status` is one of `paid`, `shipped`, `refunded`, or `failed`. Widget-mode
orders carry `ecommerceWidgetId`; cart/catalog orders carry `collectionId`.
Stripe identifiers and signed download tokens are never exposed.

## List a widget's orders

`GET /v1/ecommerce-widgets/{id}/orders` — scope `read:orders`. Paginated
(`page`, `limit`), newest first.

<CodeGroup>
  ```bash curl theme={null}
  curl https://formitto.com/v1/ecommerce-widgets/77/orders \
    -H "Authorization: Bearer fmt_live_xxxxxxxx"
  ```

  ```typescript TypeScript theme={null}
  const result = await formitto.orders.listWidgetOrders({ id: 77 });
  ```
</CodeGroup>

## Get an order

`GET /v1/orders/{id}` — scope `read:orders`.

<CodeGroup>
  ```bash curl theme={null}
  curl https://formitto.com/v1/orders/3001 \
    -H "Authorization: Bearer fmt_live_xxxxxxxx"
  ```

  ```typescript TypeScript theme={null}
  const order = await formitto.orders.getOrder({ id: 3001 });
  ```
</CodeGroup>