# Order API Documentation

## Base URL
```
http://127.0.0.1:8000/api/v1/auth/orders
```

## Authentication
All order endpoints require authentication via JWT token in the `Authorization` header:
```
Authorization: Bearer {access_token}
```

---

## 1. Get Order History By User ID

Retrieve order history by `user_id`.

**Endpoint:**
```
GET /api/v1/auth/orders?user_id={user_id}
```

**Method:** `GET`

**Authentication:** Required ✅

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | Integer | Yes | User ID to retrieve order history |

**Example Request:**
```bash
curl -X GET "http://127.0.0.1:8000/api/v1/auth/orders?user_id=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "order_number": "ORD-ABC123XYZ9",
      "status": "pending",
      "subtotal": "100.00",
      "discount": "5.00",
      "shipping_fee": "3.00",
      "total": "98.00",
      "currency": "USD",
      "payment_method": "cash",
      "shipping_detail": "Phnom Penh",
      "customer_name": "John Doe",
      "customer_phone": "012345678",
      "customer_email": "john@example.com",
      "note": "Leave at the front desk",
      "created_at": "2026-04-05T08:00:00.000000Z",
      "updated_at": "2026-04-05T08:00:00.000000Z",
      "items": [
        {
          "id": 10,
          "order_id": 1,
          "product_id": 4,
          "quantity": 2,
          "price": "50.00",
          "line_subtotal": "100.00",
          "product": {
            "id": 4,
            "name": "Product Name"
          }
        }
      ]
    }
  ]
}
```

**Response (422 Unprocessable Entity):**
```json
{
  "success": false,
  "errors": {
    "user_id": [
      "The user id field is required."
    ]
  }
}
```

---

## 2. Get Single Order By User ID

Retrieve a single order by order ID and `user_id`.

**Endpoint:**
```
GET /api/v1/auth/orders/{id}?user_id={user_id}
```

**Method:** `GET`

**Authentication:** Required ✅

**Path Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | Integer | Yes | Order ID |

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | Integer | Yes | User ID that owns the order |

**Example Request:**
```bash
curl -X GET "http://127.0.0.1:8000/api/v1/auth/orders/1?user_id=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "user_id": 1,
    "order_number": "ORD-ABC123XYZ9",
    "status": "pending",
    "subtotal": "100.00",
    "discount": "5.00",
    "shipping_fee": "3.00",
    "total": "98.00",
    "currency": "USD",
    "payment_method": "cash",
    "shipping_detail": "Phnom Penh",
    "customer_name": "John Doe",
    "customer_phone": "012345678",
    "customer_email": "john@example.com",
    "note": "Leave at the front desk",
    "items": []
  }
}
```

---

## 3. Create Order

Create a new order.

**Endpoint:**
```
POST /api/v1/auth/orders
```

**Method:** `POST`

**Authentication:** Required ✅

**Request Body:**
```json
{
  "items": [
    {
      "product_id": 1,
      "quantity": 2
    }
  ],
  "payment_method": "cash",
  "shipping_detail": "Phnom Penh",
  "customer_name": "John Doe",
  "customer_phone": "012345678",
  "customer_email": "john@example.com",
  "note": "Leave at the front desk",
  "discount": 0,
  "shipping_fee": 3,
  "currency": "USD"
}
```

**Response (201 Created):**
```json
{
  "message": "Order created successfully",
  "order": {
    "id": 1,
    "order_number": "ORD-ABC123XYZ9"
  }
}
```

---

## Admin Panel Review Features

The admin panel order management now supports:

1. Filter by `user_id`
2. Filter by `status`
3. Filter by `date_from`
4. Filter by `date_to`
5. Search by order number, customer name, email, phone, and status
6. DataTable server-side listing
7. Customer order history review from the order detail page

---

## Notes

1. `user_id` is now required for order history retrieval endpoints.
2. Order history retrieval is parameter-based using `user_id`.
3. Admin panel includes a dedicated orders menu and review workflow.