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

# List orders

> Get a paginated list of orders with optional filtering, search, and sorting

Get a paginated list of orders with optional filtering, search, and sorting

### Query parameters

<ParamField query="page" type="integer (int64)">
  Page number (default: 1)
</ParamField>

<ParamField query="limit" type="integer (int64)">
  Items per page (default: 20, max: 100)
</ParamField>

<ParamField query="status" type="OrderStatus">
  Filter by order status
</ParamField>

<ParamField query="customer_id" type="string (uuid)">
  Filter by customer ID
</ParamField>

<ParamField query="search" type="string">
  Search by order number, notes, or shipping address
</ParamField>

<ParamField query="from" type="string">
  Only include orders created after this RFC3339 timestamp
</ParamField>

<ParamField query="to" type="string">
  Only include orders created before this RFC3339 timestamp
</ParamField>

<ParamField query="sort_by" type="OrderSortField">
  Sort field (created\_at, order\_date, total\_amount, order\_number)
</ParamField>

<ParamField query="sort_order" type="SortDirection">
  Sort direction (asc, desc)
</ParamField>

<ParamField query="include_items" type="boolean">
  If true, include line items for each order in the response
</ParamField>

### Responses

<ResponseField name="200" type="ApiResponse_PaginatedResponse_OrderResponse">
  Orders retrieved successfully
</ResponseField>

<ResponseField name="400" type="ErrorResponse">
  Invalid request parameters
</ResponseField>

<ResponseField name="401" type="ErrorResponse">
  Unauthorized
</ResponseField>

<ResponseField name="403" type="ErrorResponse">
  Forbidden
</ResponseField>

<ResponseField name="429" type="ErrorResponse">
  Rate limit exceeded
</ResponseField>

<ResponseField name="500" type="ErrorResponse">
  Internal server error
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.stateset.com/api/v1/orders' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "items": [
        {
          "billing_address": {
            "city": "San Francisco",
            "country": "US",
            "postal_code": "94102",
            "state": "CA",
            "street": "123 Main Street"
          },
          "created_at": "2024-12-09T10:30:00Z",
          "currency": "USD",
          "customer_id": "123e4567-e89b-12d3-a456-426614174000",
          "fulfillment_status": "unfulfilled",
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "items": [
            {
              "id": "item-001",
              "product_id": "prod-abc123",
              "product_name": "Wireless Bluetooth Headphones",
              "quantity": 2,
              "sku": "WBH-BLK-001",
              "tax_amount": "8.00",
              "tax_rate": "0.08",
              "total_price": "99.98",
              "unit_price": "49.99"
            }
          ],
          "notes": "Please deliver to back door",
          "order_date": "2024-12-09T10:30:00Z",
          "order_number": "ORD-2024-001234",
          "payment_method_id": "pm_card_visa",
          "payment_status": "pending",
          "shipping_address": {
            "city": "San Francisco",
            "country": "US",
            "postal_code": "94102",
            "state": "CA",
            "street": "123 Main Street"
          },
          "status": "pending",
          "total_amount": "149.99",
          "updated_at": "2024-12-09T10:30:00Z",
          "version": 1
        }
      ],
      "limit": 1,
      "page": 1,
      "total": 1,
      "total_pages": 1
    },
    "errors": null,
    "message": null,
    "meta": null,
    "success": true
  }
  ```
</ResponseExample>