Products - BMS Point of Sale System

The Products API provides comprehensive endpoints for managing product catalog, inventory levels, batch tracking, and stock operations.

Get all products

Retrieve all active products in the system.

GET /api/products

Response

Returns an array of product objects ordered by name.

integer

Unique product identifier

barcode

string

Product barcode (max 50 characters)

name

string

Product name (max 200 characters)

description

string

Product description (max 500 characters)

price

decimal

Selling price

cost

decimal

Cost per unit

stockQuantity

integer

Current stock level

minStockLevel

integer

Minimum stock threshold for low stock alerts

variant

string

Product variant (e.g., size, color)

brand

string

Product brand

Example request

curl -X GET "https://api.example.com/api/products" \
  -H "Content-Type: application/json"

Get product by ID

Retrieve details of a specific product.

GET /api/products/{id}

Path parameters

integer

required

Product ID

Get product by barcode

Lookup a product using its barcode (useful for scanning operations).

GET /api/products/barcode/{barcode}

Path parameters

barcode

string

required

Product barcode

Example request

curl -X GET "https://api.example.com/api/products/barcode/1234567890" \
  -H "Content-Type: application/json"

Get low stock products

Retrieve products that are at or below their minimum stock level.

GET /api/products/low-stock

Response

Returns products where stockQuantity <= minStockLevel, ordered by stock quantity (lowest first).

Example request

curl -X GET "https://api.example.com/api/products/low-stock" \
  -H "Content-Type: application/json"

Get expiring products

Retrieve product batches that are expiring within a specified timeframe.

GET /api/products/expiring

Query parameters

days

integer

default:"30"

Number of days to look ahead for expiring products

Response

Returns an array of product batch objects with expiration dates within the specified window.

Example request

curl -X GET "https://api.example.com/api/products/expiring?days=30" \
  -H "Content-Type: application/json"

Create product

Add a new product to the catalog.

POST /api/products

Request body

barcode

string

required

Unique product barcode

name

string

required

Product name

description

string

Product description

price

decimal

required

Selling price (must be greater than zero)

cost

decimal

required

Cost per unit (cannot be negative)

stockQuantity

integer

default:"0"

Initial stock quantity (cannot be negative)

minStockLevel

integer

default:"5"

Minimum stock threshold

variant

string

Product variant

brand

string

Product brand

Example request

curl -X POST "https://api.example.com/api/products" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Admin" \
  -d '{
    "barcode": "1234567890",
    "name": "Premium Coffee Beans",
    "description": "Arabica coffee beans from Colombia",
    "price": 24.99,
    "cost": 12.50,
    "stockQuantity": 100,
    "minStockLevel": 10,
    "brand": "Colombian Gold",
    "category": "Beverages",
    "unit": "kg"
  }'

Update product

Update an existing product’s details.

PUT /api/products/{id}

Path parameters

integer

required

Product ID to update

Request body

Same as create product. The system logs price changes and flags major price adjustments (>20% change) for review.

Example request

curl -X PUT "https://api.example.com/api/products/5" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Manager" \
  -d '{
    "id": 5,
    "barcode": "1234567890",
    "name": "Premium Coffee Beans",
    "price": 29.99,
    "cost": 12.50,
    "stockQuantity": 85,
    "minStockLevel": 10,
    "isActive": true
  }'

Update stock quantity

Adjust a product’s stock quantity directly.

PUT /api/products/{id}/stock

Path parameters

integer

required

Product ID

Request body

newQuantity

integer

required

New stock quantity (cannot be negative)

reason

string

Reason for stock adjustment

Example request

curl -X PUT "https://api.example.com/api/products/5/stock" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Manager" \
  -d '{
    "newQuantity": 150,
    "reason": "Received new shipment"
  }'

Response

{
  "productId": 5,
  "oldQuantity": 85,
  "newQuantity": 150,
  "updatedAt": "2024-02-28T14:30:00Z"
}

Delete product

Permanently remove a product from the system.

DELETE /api/products/{id}

Path parameters

integer

required

Product ID to delete

Example request

curl -X DELETE "https://api.example.com/api/products/5" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Manager"

Batch management

Get product batches

Retrieve all batches for a specific product.

GET /api/products/{productId}/batches

Path parameters

productId

integer

required

Product ID

Example request

curl -X GET "https://api.example.com/api/products/5/batches" \
  -H "Content-Type: application/json"

Create product batch

Add a new batch of products with tracking information.

POST /api/products/{productId}/batches

Path parameters

productId

integer

required

Product ID

Request body

batchNumber

string

required

Unique batch identifier

quantity

integer

required

Number of units in batch (must be greater than zero)

costPerUnit

decimal

required

Cost per unit in this batch (cannot be negative)

receivedDate

string

Date batch was received (ISO 8601 format)

expirationDate

string

Expiration date (ISO 8601 format)

manufacturingDate

string

Manufacturing date (ISO 8601 format)

supplier

string

Supplier name

lotNumber

string

Lot number from manufacturer

Example request

curl -X POST "https://api.example.com/api/products/5/batches" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Inventory Manager" \
  -d '{
    "batchNumber": "BATCH-2024-001",
    "quantity": 50,
    "costPerUnit": 12.50,
    "receivedDate": "2024-02-28T10:00:00Z",
    "expirationDate": "2025-02-28T00:00:00Z",
    "supplier": "Colombian Gold Distributors",
    "lotNumber": "LOT-2024-A-123"
  }'

Overview

Endpoints

​Get all products

​Response

​Example request

​Get product by ID

​Path parameters

​Get product by barcode

​Path parameters

​Example request

​Get low stock products

​Response

​Example request

​Get expiring products

​Query parameters

​Response

​Example request

​Create product

​Request body

​Example request

​Update product

​Path parameters

​Request body

​Example request

​Update stock quantity

​Path parameters

​Request body

​Example request

​Response

​Delete product

​Path parameters

​Example request

​Batch management

​Get product batches

​Path parameters

​Example request

​Create product batch

​Path parameters

​Request body

​Example request

Build docs developers (and LLMs) love

Get all products

Response

Example request

Get product by ID

Path parameters

Get product by barcode

Path parameters

Example request

Get low stock products

Response

Example request

Get expiring products

Query parameters

Response

Example request

Create product

Request body

Example request

Update product

Path parameters

Request body

Example request

Update stock quantity

Path parameters

Request body

Example request

Response

Delete product

Path parameters

Example request

Batch management

Get product batches

Path parameters

Example request

Create product batch

Path parameters

Request body

Example request