Skip to main content

​
Overview

The Stock Management API provides atomic operations for managing product stock levels. These endpoints support the complete lifecycle of inventory management from adding new stock to consuming it during order fulfillment.

​
Stock Operations Workflow

1

Add Stock

Receive new inventory shipments and increase available stock
2

Reserve Stock

When an order is placed, reserve stock to prevent overselling
3

Consume Stock (Order Fulfilled)

When the order ships, consume the reserved stock permanently
4

Release Stock (Order Cancelled)

If an order is cancelled, release reserved stock back to available inventory

​
Add Stock

curl -X POST http://localhost:8081/api/v1/inventory/1/addStock \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100
  }'
Increases the available stock quantity for a product. Use this endpoint when receiving new inventory shipments or restocking products. POST /api/v1/inventory/{id}/addStock

​
Path Parameters

​
id
long
required
The unique identifier of the product to add stock to

​
Request Body

​
amount
integer
required
The quantity of stock to add. Must be zero or positive.

​
Request Example

{
  "amount": 100
}

​
Response

​
status
string
Returns HTTP 204 (No Content) on success

​
Example Scenario

# Product ID 1 has 50 units available
GET /api/v1/inventory/1
{
  "sku": "PROD-001",
  "availableStock": 50
}

​
Reserve Stock

curl -X POST http://localhost:8081/api/v1/inventory/1/reserveStock \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5
  }'
Reserves stock for a pending order. This operation decreases available stock without permanently removing it, preventing overselling while orders are being processed. POST /api/v1/inventory/{id}/reserveStock

​
Path Parameters

​
id
long
required
The unique identifier of the product to reserve stock from

​
Request Body

​
amount
integer
required
The quantity of stock to reserve. Must be zero or positive. Cannot exceed available stock.

​
Request Example

{
  "amount": 5
}

​
Response

​
status
string
Returns HTTP 204 (No Content) on success

​
Example Scenario

# Product has 150 units available
GET /api/v1/inventory/1
{
  "sku": "PROD-001",
  "availableStock": 150
}
If the requested amount exceeds available stock, the operation will fail. Always check available stock before reserving.

​
Release Stock

curl -X POST http://localhost:8081/api/v1/inventory/1/releaseStock \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5
  }'
Releases previously reserved stock back to available inventory. Use this endpoint when an order is cancelled or a reservation expires. POST /api/v1/inventory/{id}/releaseStock

​
Path Parameters

​
id
long
required
The unique identifier of the product to release stock for

​
Request Body

​
amount
integer
required
The quantity of stock to release. Must be zero or positive.

​
Request Example

{
  "amount": 5
}

​
Response

​
status
string
Returns HTTP 204 (No Content) on success

​
Example Scenario

# Product has 145 units available (5 reserved)
GET /api/v1/inventory/1
{
  "sku": "PROD-001",
  "availableStock": 145
}

​
Consume Stock

curl -X POST http://localhost:8081/api/v1/inventory/1/consumeStock \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5
  }'
Permanently reduces stock when an order is fulfilled and shipped. This operation finalizes the stock reduction that was initially reserved. POST /api/v1/inventory/{id}/consumeStock

​
Path Parameters

​
id
long
required
The unique identifier of the product to consume stock from

​
Request Body

​
amount
integer
required
The quantity of stock to consume. Must be zero or positive.

​
Request Example

{
  "amount": 5
}

​
Response

​
status
string
Returns HTTP 204 (No Content) on success

​
Example Scenario

# Product has 145 units available (5 reserved)
GET /api/v1/inventory/1
{
  "sku": "PROD-001",
  "availableStock": 145
}
The consume operation typically affects reserved stock, not available stock. The available stock was already reduced during the reserve operation.

​
Complete Order Lifecycle Example

# 1. Initial state: 100 units available
GET /api/v1/inventory/1
Response: { "availableStock": 100 }

# 2. Customer places order for 3 units
POST /api/v1/inventory/1/reserveStock
Body: { "amount": 3 }
Response: 204 No Content

# 3. Check stock: 97 units available
GET /api/v1/inventory/1
Response: { "availableStock": 97 }

# 4. Order ships - consume the reserved stock
POST /api/v1/inventory/1/consumeStock
Body: { "amount": 3 }
Response: 204 No Content

# 5. Final state: 97 units available
GET /api/v1/inventory/1
Response: { "availableStock": 97 }

​
Best Practices

In a typical order workflow, always call reserveStock when the order is placed, then call consumeStock when the order is fulfilled. This prevents overselling and maintains accurate inventory counts.
If an order is cancelled after stock has been reserved, always call releaseStock to return the inventory to available status. Failing to do this will result in “phantom” reservations that reduce available stock indefinitely.
The service implements proper concurrency controls, but applications should still handle potential race conditions when multiple orders are placed simultaneously for products with low stock.
Before attempting to reserve stock, check the availableStock field to ensure sufficient inventory exists. This provides better user experience than waiting for a reservation failure.

​
Error Handling

All stock management endpoints can return the following errors:
Status CodeDescriptionSolution
400Invalid request (e.g., negative amount)Ensure amount is zero or positive
404Product not foundVerify the product ID exists
409Insufficient stock for reservationCheck available stock before reserving
500Internal server errorRetry the request or contact support
Stock operations are atomic and transactional. If an operation fails, no changes are made to the inventory.

Build docs developers (and LLMs) love

Get started for freeTalk to us