Skip to main content
The Inventory API provides endpoints for performing inventory counts and managing stock adjustments with approval workflows.

​
Inventory counts

​
Get all inventory counts

Retrieve all inventory count sessions. 
GET /api/inventorycount

​
Response

​
id
integer
Unique count identifier
​
countName
string
Name of the inventory count
​
countType
string
Type: FULL, CYCLE, SPOT, or ANNUAL
​
startedDate
string
When count was started
​
completedDate
string
When count was completed
​
status
string
Status: IN_PROGRESS, COMPLETED, or CANCELLED
​
totalItemsCounted
integer
Number of items counted
​
totalDiscrepancies
integer
Number of items with discrepancies
​
totalShrinkageValue
decimal
Total value of missing inventory
​
totalOverageValue
decimal
Total value of excess inventory
​
netVarianceValue
decimal
Net variance in inventory value

​
Start inventory count

Begin a new inventory count session. Only managers can start counts. 
POST /api/inventorycount

​
Request body

​
countName
string
required
Name for this count session
​
countType
string
required
Type: FULL, CYCLE, SPOT, or ANNUAL
​
notes
string
Additional notes

​
Example request

curl -X POST "https://api.example.com/api/inventorycount" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Manager" \
  -d '{
    "countName": "Monthly Inventory - March 2024",
    "countType": "FULL",
    "notes": "End of month full inventory count"
  }'

​
Validation

  • Only one inventory count can be in progress at a time
  • Only managers can start inventory counts

​
Get inventory count by ID

Retrieve details of a specific count. 
GET /api/inventorycount/{id}

​
Add count item

Record the counted quantity for a product. 
POST /api/inventorycount/{countId}/items

​
Path parameters

​
countId
integer
required
Inventory count ID

​
Request body

​
productId
integer
required
Product being counted
​
productBatchId
integer
Specific batch being counted (optional)
​
countedQuantity
integer
required
Actual quantity counted
​
discrepancyReason
string
Reason for discrepancy
​
notes
string
Additional notes

​
Example request

curl -X POST "https://api.example.com/api/inventorycount/1/items" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Inventory Staff" \
  -d '{
    "productId": 5,
    "countedQuantity": 82,
    "discrepancyReason": "3 units missing from shelf"
  }'

​
Response

The system automatically:
  • Compares counted quantity with system quantity
  • Calculates variance (positive or negative)
  • Calculates variance value based on product cost
  • Logs significant discrepancies for review

​
Get count items

Retrieve all items counted in a session. 
GET /api/inventorycount/{countId}/items

​
Complete inventory count

Finalize a count session and optionally apply adjustments. 
PUT /api/inventorycount/{id}/complete

​
Path parameters

​
id
integer
required
Inventory count ID

​
Request body

​
applyAdjustments
boolean
default:"true"
Whether to apply stock adjustments
​
completionNotes
string
Notes about completion

​
Example request

curl -X PUT "https://api.example.com/api/inventorycount/1/complete" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Manager" \
  -d '{
    "applyAdjustments": true,
    "completionNotes": "All discrepancies reviewed and approved"
  }'
When applyAdjustments is true:
  • Product stock quantities are updated to match counted quantities
  • Automatic stock adjustment records are created
  • All adjustments are pre-approved

​
Cancel inventory count

Cancel an in-progress count. 
DELETE /api/inventorycount/{id}

​
Get inventory summary

Get aggregated statistics for inventory counts. 
GET /api/inventorycount/summary

​
Query parameters

​
startDate
string
Filter from date (ISO 8601)
​
endDate
string
Filter to date (ISO 8601)

​
Stock adjustments

​
Get stock adjustments

Retrieve stock adjustment records. 
GET /api/stockadjustments

​
Query parameters

​
startDate
string
Filter from date (ISO 8601)
​
endDate
string
Filter to date (ISO 8601)
​
productId
integer
Filter by product ID

​
Response

​
id
integer
Adjustment ID
​
productId
integer
Product adjusted
​
adjustmentType
string
Type: DAMAGE, THEFT, EXPIRED, FOUND, CORRECTION, or RETURN
​
quantityChange
integer
Change in quantity (positive or negative)
​
quantityBefore
integer
Stock quantity before adjustment
​
quantityAfter
integer
Stock quantity after adjustment
​
reason
string
Reason for adjustment
​
costImpact
decimal
Financial impact of adjustment
​
requiresApproval
boolean
Whether approval is required
​
isApproved
boolean
Whether adjustment is approved

​
Create stock adjustment

Create a manual stock adjustment. 
POST /api/stockadjustments

​
Request body

​
productId
integer
required
Product to adjust
​
adjustmentType
string
required
Type: DAMAGE, THEFT, EXPIRED, FOUND, CORRECTION, or RETURN
​
quantityChange
integer
required
Change in quantity (use negative for decreases)
​
reason
string
required
Reason for adjustment
​
notes
string
Additional notes
​
referenceNumber
string
Reference number (e.g., damage report ID)

​
Example request

curl -X POST "https://api.example.com/api/stockadjustments" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Inventory Manager" \
  -d '{
    "productId": 5,
    "adjustmentType": "DAMAGE",
    "quantityChange": -3,
    "reason": "Water damage from roof leak",
    "notes": "Damaged during heavy rain on 2024-02-27",
    "referenceNumber": "DMG-2024-001"
  }'

​
Approval workflow

Adjustments require manager approval when:
  • Absolute quantity change > 50 units
  • Absolute cost impact > $500
  • Adjustment type is THEFT
Unapproved adjustments are recorded but don’t affect stock until approved.

​
Get pending approvals

Get adjustments awaiting manager approval. 
GET /api/stockadjustments/pending-approval

​
Approve adjustment

Approve a pending stock adjustment. Only managers can approve. 
PUT /api/stockadjustments/{id}/approve

​
Path parameters

​
id
integer
required
Adjustment ID to approve

​
Request body

​
approvalNotes
string
Notes about approval

​
Example request

curl -X PUT "https://api.example.com/api/stockadjustments/5/approve" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Manager" \
  -d '{
    "approvalNotes": "Reviewed damage report, approved for write-off"
  }'

​
Get product adjustments

Get all adjustments for a specific product. 
GET /api/stockadjustments/product/{productId}

​
Path parameters

​
productId
integer
required
Product ID

Build docs developers (and LLMs) love

Get started for freeTalk to us