Overview
The Inventory API provides comprehensive endpoints for managing inventory items, including CRUD operations, quantity updates, and analytics. All endpoints require authentication.
Get All Inventory
Retrieve all inventory items with pagination and filtering.
Access: Private (all authenticated users)
Query Parameters
Page number for pagination
Filter by category (case-insensitive)
Filter by supplier (case-insensitive)
Search by product name or SKU
Field to sort by (e.g., quantity, expiryDate)
Response
Example Response
{
"success": true,
"message": "Inventory items fetched successfully",
"data": {
"items": [
{
"_id": "65a1234567890abcdef12345",
"productName": "Organic Apples",
"category": "Fruits",
"sku": "FRT-001",
"quantity": 150,
"purchaseDate": "2024-01-15T00:00:00.000Z",
"expiryDate": "2024-02-15T00:00:00.000Z",
"supplier": "Fresh Farms Ltd",
"createdBy": {
"_id": "65a9876543210fedcba98765",
"name": "Admin User",
"email": "[email protected]"
}
}
],
"pagination": {
"currentPage": 1,
"totalPages": 5,
"totalItems": 50,
"limit": 10
}
}
}
Get Inventory Item
Get a single inventory item by ID.
Access: Private (all authenticated users)
Response
{
"success": true,
"message": "Inventory item fetched successfully",
"data": {
"item": {
"_id": "65a1234567890abcdef12345",
"productName": "Organic Apples",
"category": "Fruits",
"sku": "FRT-001",
"quantity": 150,
"purchaseDate": "2024-01-15T00:00:00.000Z",
"expiryDate": "2024-02-15T00:00:00.000Z",
"supplier": "Fresh Farms Ltd"
}
}
}
Create Inventory Item
Create a new inventory item.
Access: Private (Admin/Manager only)
Request Body
Stock Keeping Unit (will be converted to uppercase)
Initial quantity in stock
Purchase date (ISO 8601 format)
Expiry date (must be after purchase date)
Example Request
{
"productName": "Organic Apples",
"category": "Fruits",
"sku": "FRT-001",
"quantity": 150,
"purchaseDate": "2024-01-15",
"expiryDate": "2024-02-15",
"supplier": "Fresh Farms Ltd"
}
Update Inventory Item
Update an existing inventory item.
Access: Private (Admin/Manager only)
Request Body
All fields are optional. Only provided fields will be updated.
Update Quantity
Quickly update inventory quantity with add, subtract, or set operations.
Access: Private (Admin/Manager only)
Request Body
Operation type: add, subtract, or set
Example Request
{
"quantity": 50,
"operation": "add"
}
Example Response
{
"success": true,
"message": "Inventory quantity updated successfully",
"data": {
"item": {
"_id": "65a1234567890abcdef12345",
"productName": "Organic Apples",
"quantity": 200,
"lastModifiedBy": {
"name": "Manager User",
"email": "[email protected]"
}
}
}
}
Delete Inventory Item
Delete an inventory item.
Access: Private (Admin/Manager only)
Response
{
"success": true,
"message": "Inventory item deleted successfully",
"data": null
}
Analytics Endpoints
Get Inventory by Category
Get aggregated inventory data grouped by category.
Access: Private (all authenticated users)
Response
{
"success": true,
"message": "Category analytics fetched successfully",
"data": {
"categories": [
{
"category": "Fruits",
"totalQuantity": 500,
"itemCount": 5,
"avgQuantity": 100
}
]
}
}
Get Inventory by Supplier
Get aggregated inventory data grouped by supplier.
Access: Private (all authenticated users)
Response
{
"success": true,
"message": "Supplier analytics fetched successfully",
"data": {
"suppliers": [
{
"supplier": "Fresh Farms Ltd",
"totalQuantity": 750,
"itemCount": 8,
"categories": ["Fruits", "Vegetables"]
}
]
}
}
Get Inventory Summary
Get dashboard summary statistics.
Access: Private (all authenticated users)
Response
{
"success": true,
"message": "Inventory summary fetched successfully",
"data": {
"summary": {
"totalItems": 50,
"totalQuantity": 2500,
"categoriesCount": 8,
"suppliersCount": 12,
"lowStockCount": 5,
"outOfStockCount": 2,
"expiringSoonCount": 3,
"expiredCount": 1
}
}
}