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

# Products

> Manage and query products through the external API

The Products API allows external systems to synchronize product catalogs, query real-time stock levels, and submit inventory stock adjustment requests.

***

## Stock Adjustment Request Workflow

Stock adjustments submitted via the API undergo approval before mutating live inventory levels:

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING: POST /api/v1/external/products/adjust
    PENDING --> APPROVED: Admin / System Approves
    PENDING --> REJECTED: Stock Audit Declined
    APPROVED --> [*]: Stock Updated & Ledger Recorded
    REJECTED --> [*]: Request Voided
```

***

### 1. Get All Products

Retrieve a paginated list of products.

```http theme={null}
GET /api/v1/external/products
```

#### Query Parameters

| Parameter | Type   | Required | Description                                  | Example  |
| :-------- | :----- | :------- | :------------------------------------------- | :------- |
| `page`    | number | No       | Page number (default: `1`)                   | `1`      |
| `limit`   | number | No       | Results per page (default: `10`, max: `100`) | `20`     |
| `search`  | string | No       | Search query for product name or SKU         | `Coffee` |

#### Success Response (`200 OK`)

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "Standard Product",
      "slug": "standard-product",
      "price": 1500,
      "sku": "SKU-1001"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10
  }
}
```

#### Error Responses

##### Invalid Query Parameter (`400 Bad Request`)

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "limit must not be greater than 100"
}
```

***

### 2. Get Low Stock Products

Retrieve a list of products that have fallen below their minimum stock threshold.

```http theme={null}
GET /api/v1/external/products/stock
```

#### Success Response (`200 OK`)

```json theme={null}
{
  "success": true,
  "data": {
    "productCount": 15,
    "status": "OUT_OF_STOCK"
  }
}
```

#### Error Responses

##### Missing or Invalid Client ID (`401 Unauthorized`)

```json theme={null}
{
  "success": false,
  "status": 401,
  "message": "Invalid or inactive Client ID or API Key."
}
```

***

### 3. Update Product

Update details of an existing product.

```http theme={null}
PUT /api/v1/external/products/:id
```

#### Path Parameters

* `id` (string, required): The UUID of the product.

#### Request Body

```json theme={null}
{
  "name": "Updated Product Name",
  "price": 1600
}
```

#### Success Response (`200 OK`)

```json theme={null}
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "Updated Product Name",
    "price": 1600
  }
}
```

#### Error Responses

##### Product Not Found (`404 Not Found`)

```json theme={null}
{
  "success": false,
  "status": 404,
  "message": "Product not found"
}
```

##### Validation Error (`400 Bad Request`)

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "price must be a positive number"
}
```

***

### 4. Submit Stock Adjustment Request

Create a request to adjust inventory stock levels of products.

```http theme={null}
POST /api/v1/external/products/adjust
```

#### Request Body Example

```json theme={null}
{
  "warehouseId": "w1e2r3t4-y5u6-i7o8-p9a0-s1d2f3g4h5j6",
  "reason": "Damaged stock replacement",
  "items": [
    {
      "productId": "p1o2i3u4-y5t6-r7e8-w9q0-l1k2j3h4g5f6",
      "quantity": 10,
      "type": "STOCK_IN"
    }
  ]
}
```

#### Success Response (`201 Created`)

```json theme={null}
{
  "success": true,
  "data": {
    "id": "adj-uuid-12345",
    "warehouseId": "w1e2r3t4-y5u6-i7o8-p9a0-s1d2f3g4h5j6",
    "status": "PENDING",
    "reason": "Damaged stock replacement",
    "items": [
      {
        "productId": "p1o2i3u4-y5t6-r7e8-w9q0-l1k2j3h4g5f6",
        "quantity": 10,
        "type": "STOCK_IN"
      }
    ]
  }
}
```

#### Error Responses

##### Insufficient Available Stock / Validation Error (`400 Bad Request`)

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "Row 1: Items quantity must be a positive number"
}
```

##### Warehouse Not Found (`404 Not Found`)

```json theme={null}
{
  "success": false,
  "status": 404,
  "message": "Warehouse not found"
}
```

***

### 5. Get Stock Adjustment Requests

Retrieve a paginated list of stock adjustment requests.

```http theme={null}
GET /api/v1/external/products/adjustments
```

#### Success Response (`200 OK`)

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "adj-uuid-12345",
      "warehouseId": "w1e2r3t4-y5u6-i7o8-p9a0-s1d2f3g4h5j6",
      "status": "APPROVED",
      "reason": "Damaged stock replacement"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10
  }
}
```

#### Error Responses

##### Invalid Status Filter (`400 Bad Request`)

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "status must be one of the following values: PENDING, APPROVED, REJECTED"
}
```