Health check Check the health status of the Inventory Service, including database and Redis connectivity.
Response Always true for successful health checks
Status message - always “service is healthy”
Health status - always “ok”
Example curl http://localhost:8080/health
{ "success" : true , "message" : "service is healthy" , "data" : { "status" : "ok" } }
Initialize inventory Create a new inventory record for a product with an initial stock quantity. This operation is idempotent - if inventory already exists for the product, it is not modified.
Body parameters Unique identifier for the product
Initial available quantity (must be >= 0)
Response Indicates if the operation succeeded
Show InventoryStock properties
Quantity available for reservation
Quantity currently reserved for pending orders
ISO 8601 timestamp of inventory creation
ISO 8601 timestamp of last update
Example curl -X POST http://localhost:8080/inventory/init \ -H "Content-Type: application/json" \ -d '{ "productId": "prod_001", "quantity": 100 }'
{ "success" : true , "message" : "inventory initialized" , "data" : { "productId" : "prod_001" , "availableQuantity" : 100 , "reservedQuantity" : 0 , "createdAt" : "2026-03-03T10:30:00Z" , "updatedAt" : "2026-03-03T10:30:00Z" } }
Get inventory Retrieve current stock levels for a specific product.
Path parameters Response Indicates if the operation succeeded
Show InventoryStock properties
Quantity available for reservation
Quantity currently reserved for pending orders
ISO 8601 timestamp of inventory creation
ISO 8601 timestamp of last update
Example curl http://localhost:8080/inventory/prod_001
{ "success" : true , "message" : "inventory fetched" , "data" : { "productId" : "prod_001" , "availableQuantity" : 85 , "reservedQuantity" : 15 , "createdAt" : "2026-03-03T10:30:00Z" , "updatedAt" : "2026-03-03T11:45:00Z" } }
Add stock Increase the available quantity for an existing product. The operation uses row-level locking to ensure thread safety.
Body parameters Amount to add to available stock (must be > 0)
Response Indicates if the operation succeeded
Show InventoryStock properties
Updated available quantity after adding stock
Reserved quantity (unchanged)
ISO 8601 timestamp of inventory creation
ISO 8601 timestamp of this update
Example curl -X POST http://localhost:8080/inventory/add-stock \ -H "Content-Type: application/json" \ -d '{ "productId": "prod_001", "quantity": 50 }'
{ "success" : true , "message" : "stock added" , "data" : { "productId" : "prod_001" , "availableQuantity" : 135 , "reservedQuantity" : 15 , "createdAt" : "2026-03-03T10:30:00Z" , "updatedAt" : "2026-03-03T12:00:00Z" } }
Reserve stock Reserve inventory for a pending order. Stock is moved from available to reserved, and a reservation record is created with an expiration time. The reservation is also cached in Redis.
Body parameters Order identifier that owns this reservation
Quantity to reserve (must be > 0)
Response Indicates if the operation succeeded
Show InventoryReservation properties
Unique reservation identifier (UUID)
Reservation status - always “RESERVED” for new reservations
ISO 8601 timestamp when reservation expires
ISO 8601 timestamp of reservation creation
Example curl -X POST http://localhost:8080/inventory/reserve \ -H "Content-Type: application/json" \ -d '{ "productId": "prod_001", "orderId": "order_123", "quantity": 5 }'
{ "success" : true , "message" : "stock reserved" , "data" : { "reservationId" : "550e8400-e29b-41d4-a716-446655440000" , "productId" : "prod_001" , "orderId" : "order_123" , "quantity" : 5 , "status" : "RESERVED" , "expiresAt" : "2026-03-03T12:30:00Z" , "createdAt" : "2026-03-03T12:00:00Z" } }
Release reservation Release a reservation and return stock to the available pool. Use this when an order is cancelled or fails. The operation checks Redis cache before querying the database for improved performance.
Body parameters Reservation identifier to release
Response Indicates if the operation succeeded
Show InventoryReservation properties
Unique reservation identifier
Quantity that was released
Updated status - “RELEASED”
ISO 8601 timestamp of original expiration
ISO 8601 timestamp of original creation
Example curl -X POST http://localhost:8080/inventory/release \ -H "Content-Type: application/json" \ -d '{ "reservationId": "550e8400-e29b-41d4-a716-446655440000" }'
200 Response
409 Error - Already Released
409 Error - Already Deducted
{ "success" : true , "message" : "reservation released" , "data" : { "reservationId" : "550e8400-e29b-41d4-a716-446655440000" , "productId" : "prod_001" , "orderId" : "order_123" , "quantity" : 5 , "status" : "RELEASED" , "expiresAt" : "2026-03-03T12:30:00Z" , "createdAt" : "2026-03-03T12:00:00Z" } }
Deduct reservation Permanently deduct reserved stock when an order is successfully completed. This moves the reservation to the DEDUCTED state and decrements the reserved quantity without returning it to available stock.
Body parameters Reservation identifier to deduct
Response Indicates if the operation succeeded
Show InventoryReservation properties
Unique reservation identifier
Quantity that was deducted
Updated status - “DEDUCTED”
ISO 8601 timestamp of original expiration
ISO 8601 timestamp of original creation
Example curl -X POST http://localhost:8080/inventory/deduct \ -H "Content-Type: application/json" \ -d '{ "reservationId": "550e8400-e29b-41d4-a716-446655440000" }'
200 Response
409 Error - Already Deducted
409 Error - Already Released
{ "success" : true , "message" : "reservation deducted" , "data" : { "reservationId" : "550e8400-e29b-41d4-a716-446655440000" , "productId" : "prod_001" , "orderId" : "order_123" , "quantity" : 5 , "status" : "DEDUCTED" , "expiresAt" : "2026-03-03T12:30:00Z" , "createdAt" : "2026-03-03T12:00:00Z" } }