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:

---

1. Get All Products

Retrieve a paginated list of products.

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)

{
  "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)

{
  "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.

GET /api/v1/external/products/stock

Success Response (200 OK)

{
  "success": true,
  "data": {
    "productCount": 15,
    "status": "OUT_OF_STOCK"
  }
}

Error Responses

Missing or Invalid Client ID (401 Unauthorized)

{
  "success": false,
  "status": 401,
  "message": "Invalid or inactive Client ID or API Key."
}

---

3. Update Product

Update details of an existing product.

PUT /api/v1/external/products/:id

Path Parameters

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

Request Body

{
  "name": "Updated Product Name",
  "price": 1600
}

Success Response (200 OK)

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

Error Responses

Product Not Found (404 Not Found)

{
  "success": false,
  "status": 404,
  "message": "Product not found"
}

Validation Error (400 Bad Request)

{
  "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.

POST /api/v1/external/products/adjust

Request Body Example

{
  "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)

{
  "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)

{
  "success": false,
  "status": 400,
  "message": "Row 1: Items quantity must be a positive number"
}

Warehouse Not Found (404 Not Found)

{
  "success": false,
  "status": 404,
  "message": "Warehouse not found"
}

---

5. Get Stock Adjustment Requests

Retrieve a paginated list of stock adjustment requests.

GET /api/v1/external/products/adjustments

Success Response (200 OK)

{
  "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)

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