Inventory Stock Management

4 API calls in this section.

Endpoints for managing inventory stock levels and movements within warehouses. These APIs provide real-time tracking of item quantities across different bin locations, supporting lot and serial number tracking, expiration date management, and historical stock level tracking.

List Inventory Stock

Warehousing / Inventory Stock Management

GET/warehousing/inventory-stock

Retrieves inventory stock levels with comprehensive filtering options for a specific warehouse. Provides detailed information about item quantities in specific bin locations, including status, lot numbers, and expiration dates.

• User must have 'view:tenant' or 'manage:operations:tenant' permission

Business Rules

• statusCounts and stats use the same tenant, warehouse, item, bin, search, lot, serial, quantity, reserved quantity, item name, and updated-date filters as the list.

• Only the selected status filter is excluded from counters, so all Stock Levels tab counts remain available.

• Counters are grouped in PostgreSQL; the Edge Function does not download all tenant stock rows to calculate them.

Response

• Returns a paginated list of inventory stock records scoped to the specified warehouse

• Includes details of the items, bins, and warehouses

• Each stock row preserves has_exception, has_open_exception, and the latest open_exception, and also returns every open_exceptions entry plus open_exception_count

• The deprecated singular exception alias is not returned

• Includes pagination information (total count, current page, limit)

Frontend integration contract

Continue sending the selected warehouse as warehouse_id and use statusCounts.total, available, reserved, damaged, and expired for the tabs. Render the stock exception indicator from stock[].has_exception; open stock[].open_exceptions to show every current flag. Use stock[].open_exception only when a singular newest open exception is needed; stock[].exception is no longer returned.

Query parameters

Parameter	Type	Description
tenant_idRequired	string	UUID of the tenant (required) UUID of the tenant (required) Example: {{tenant_id}}
warehouse_idRequired	string	UUID of the warehouse (required) UUID of the warehouse whose stock should be listed UUID of the warehouse (required) UUID of the warehouse whose stock should be listed Example: {{warehouse_id}}
item_idOptional	string	Filter by inventory item (optional) Filter by inventory item (optional)
bin_idOptional	string	Filter by bin location (optional) Filter by bin location (optional)
statusOptional	string	Filter by stock status (optional) Filter by stock status (available, reserved, damaged, expired) Filter by stock status (optional) Filter by stock status (available, reserved, damaged, expired)
searchOptional	string	Search in lot number and serial number (optional) Search in lot number and serial number (optional)
lot_numberOptional	string	Filter by lot number (optional) Filter by lot number (optional)
min_quantityOptional	string	Filter by minimum quantity (optional) Filter by minimum quantity (optional)
max_quantityOptional	string	Filter by maximum quantity (optional) Filter by maximum quantity (optional)
pageOptional	string	Page number for pagination (optional, default: 1) Page number for pagination (default: 1) Page number for pagination (optional, default: 1) Page number for pagination (default: 1) Example: 1
limitOptional	string	Number of items per page (optional, default: 20) Number of items per page (default: 20) Number of items per page (optional, default: 20) Number of items per page (default: 20) Example: 20

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/warehousing/inventory-stock?tenant_id=${TENANT_ID}&warehouse_id=${WAREHOUSE_ID}&item_id=&bin_id=&status=&search=&lot_number=&min_quantity=&max_quantity=&page=1&limit=20" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200 · Success Response404 · Error - Tenant Not Found403 · Error - Insufficient Permissions500 · Error - Server Error

200Success Response

Response body

json

1{2  "success": true,3  "message": "Inventory stock retrieved successfully",4  "stock": [5    {6      "id": "stock-uuid-1",7      "tenant_id": "tenant-uuid",8      "warehouse_id": "warehouse-uuid",9      "item_id": "item-uuid",10      "bin_id": "bin-uuid",11      "quantity": 100,12      "unit_of_measure": "ea",13      "status": "available",14      "has_exception": true,15      "has_open_exception": true,16      "open_exception": {17        "id": "exception-uuid",18        "exception_type": "damaged",19        "exception_label": "Damaged",20        "status": "open",21        "affected_quantity": 1,22        "exception_details": {23          "damage_area": "corner"24        },25        "notes": "Box crushed on arrival",26        "reported_at": "2026-06-30T10:00:00Z",27        "updated_at": "2026-06-30T10:00:00Z"28      },29      "lot_number": "LOT123",30      "serial_number": null,31      "expiration_date": "2024-12-31T00:00:00Z",32      "received_date": "2023-06-15T00:00:00Z",33      "last_counted_at": "2023-06-15T10:30:00Z",34      "created_at": "2023-06-15T09:45:00Z",35      "updated_at": "2023-06-15T09:45:00Z",36      "item": {37        "id": "item-uuid",38        "name": "Test Product",39        "sku": "ITEM-001",40        "barcode": "123456789",41        "category": "Electronics",42        "item_type": "finished_good"43      },44      "bin": {45        "id": "bin-uuid",46        "name": "Bin A1",47        "code": "B-001",48        "location_type": "bin"49      },50      "warehouse": {51        "id": "warehouse-uuid",52        "name": "Main Warehouse",53        "code": "WH001"54      },55      "open_exceptions": [56        {57          "id": "exception-uuid",58          "exception_type": "damaged",59          "exception_label": "Damaged",60          "status": "open",61          "affected_quantity": 1,62          "exception_details": {63            "damage_area": "corner"64          },65          "notes": "Box crushed on arrival",66          "reported_at": "2026-06-30T10:00:00Z",67          "updated_at": "2026-06-30T10:00:00Z"68        }69      ],70      "open_exception_count": 171    }72  ],73  "statusCounts": {74    "available": 1,75    "reserved": 0,76    "damaged": 0,77    "expired": 078  },79  "stats": {80    "available": 1,81    "reserved": 0,82    "damaged": 0,83    "expired": 084  },85  "page": 1,86  "limit": 20,87  "total": 188}

Create/Update Inventory Stock

Warehousing / Inventory Stock Management

POST/warehousing/inventory-stock

Creates or updates inventory stock for an item in a specific bin location. If a stock record already exists for the specified warehouse-item-bin combination, it updates the quantity; otherwise, it creates a new stock record. Also creates a transaction record to track the change.

• User must have 'manage:operations:tenant' permission

Business Rules

• Warehouse must exist and belong to the specified tenant

• Item must exist and belong to the tenant

• Bin must exist, belong to the specified warehouse, and be of location_type "bin"

• Quantity must be a non-negative number

• Status must be one of: available, reserved, damaged, expired

• If stock record already exists, it will be updated; otherwise, a new record is created

• An inventory transaction record is automatically created to track the stock change

Query parameters

Parameter	Type	Description
tenant_idRequired	string	UUID of the tenant (required) UUID of the tenant (required) Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
warehouse_id	string	—
item_id	string	—
bin_id	string	—
quantity	number	—
unit_of_measure	string	—
status	string	—
lot_number	string	—
serial_number	null	—
expiration_date	string	—
received_date	string	—
last_counted_at	string	—
notes	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/warehousing/inventory-stock?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "warehouse_id": "{{warehouse_id}}",6  "item_id": "{{item_id}}",7  "bin_id": "{{bin_id}}",8  "quantity": 100,9  "unit_of_measure": "ea",10  "status": "available",11  "lot_number": "LOT123",12  "serial_number": null,13  "expiration_date": "2024-12-31T00:00:00Z",14  "received_date": "2023-06-15T00:00:00Z",15  "last_counted_at": "2023-06-15T10:30:00Z",16  "notes": "Initial stock for product launch"17}'

Replace {{placeholders}} with your own values before sending.

Other request examples (1)

Request example 1

text

1{2  "warehouse_id": "uuid", // required3  "item_id": "uuid", // required4  "bin_id": "uuid", // required5  "quantity": number, // required, non-negative6  "unit_of_measure": "string", // required (e.g., "each", "box", "kg")7  "status": "string", // required (available, reserved, damaged, expired)8  "lot_number": "string", // optional9  "serial_number": "string", // optional10  "expiration_date": "date", // optional11  "received_date": "date", // required12  "last_counted_at": "date", // optional13  "notes": "string" // optional14}

Response examples

201 · Success Response - Created200 · Success Response - Updated400 · Error - Missing Required Field400 · Error - Quantity Must Be Non-Negative400 · Error - Invalid Status400 · Error - Location Not A Bin404 · Error - Warehouse Not Found404 · Error - Item Not Found404 · Error - Bin Not Found403 · Error - Insufficient Permissions

201Success Response - Created

Response body

json

1{2  "success": true,3  "message": "Inventory stock created successfully",4  "stock": {5    "id": "stock-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "item_id": "item-uuid",9    "bin_id": "bin-uuid",10    "quantity": 100,11    "unit_of_measure": "ea",12    "status": "available",13    "lot_number": "LOT123",14    "serial_number": null,15    "expiration_date": "2024-12-31T00:00:00Z",16    "received_date": "2023-06-15T00:00:00Z",17    "last_counted_at": "2023-06-15T10:30:00Z",18    "created_at": "2023-06-15T09:45:00Z",19    "updated_at": "2023-06-15T09:45:00Z",20    "item": {21      "id": "item-uuid",22      "name": "Test Product",23      "sku": "ITEM-001"24    },25    "bin": {26      "id": "bin-uuid",27      "name": "Bin A1",28      "code": "B-001"29    },30    "warehouse": {31      "id": "warehouse-uuid",32      "name": "Main Warehouse",33      "code": "WH001"34    }35  },36  "operation": "created"37}

Get Inventory Stock

Warehousing / Inventory Stock Management

GET/warehousing/inventory-stock/:id

Retrieves details of a specific inventory stock record, including its transaction history and current warehouse exceptions. Provides comprehensive information about the item, bin location, and warehouse.

• User must have 'view:tenant' or 'manage:operations:tenant' permission

Response

• Returns detailed information about the specified inventory stock record

• Includes related item, bin, and warehouse details

• Includes transaction history for the stock (limited to most recent 5 transactions)

• stock.open_exceptions contains every currently open warehouse exception for the related inventory item; resolved exceptions are excluded

• stock.open_exception is the newest open exception and stock.open_exception_count is the number of open exceptions

• stock.has_open_exception and stock.has_exception remain boolean indicators

• The deprecated stock.exception alias is not returned

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the inventory stock record (required) UUID of the inventory stock record (required) Example: stock-uuid

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) UUID of the tenant (required if not in auth) Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/warehousing/inventory-stock/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200 · Success Response404 · Error - Stock Not Found400 · Error - Stock ID Required404 · Error - Tenant Not Found403 · Error - Insufficient Permissions

200Success Response

Response body

json

1{2  "success": true,3  "message": "Inventory stock retrieved successfully",4  "stock": {5    "id": "stock-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "item_id": "item-uuid",9    "bin_id": "bin-uuid",10    "quantity": 100,11    "unit_of_measure": "ea",12    "status": "available",13    "has_exception": true,14    "has_open_exception": true,15    "open_exception": {16      "id": "exception-uuid",17      "exception_type": "wrong_item",18      "exception_label": "Wrong Item",19      "status": "open"20    },21    "open_exceptions": [22      {23        "id": "exception-uuid",24        "exception_type": "wrong_item",25        "exception_label": "Wrong Item",26        "status": "open"27      }28    ],29    "open_exception_count": 1,30    "lot_number": "LOT123",31    "serial_number": null,32    "expiration_date": "2024-12-31T00:00:00Z",33    "received_date": "2023-06-15T00:00:00Z",34    "last_counted_at": "2023-06-15T10:30:00Z",35    "created_at": "2023-06-15T09:45:00Z",36    "updated_at": "2023-06-15T09:45:00Z",37    "item": {38      "id": "item-uuid",39      "name": "Test Product",40      "sku": "ITEM-001",41      "barcode": "123456789",42      "category": "Electronics",43      "item_type": "finished_good"44    },45    "bin": {46      "id": "bin-uuid",47      "name": "Bin A1",48      "code": "B-001",49      "location_type": "bin"50    },51    "warehouse": {52      "id": "warehouse-uuid",53      "name": "Main Warehouse",54      "code": "WH001"55    }56  },57  "transactions": [58    {59      "id": "transaction-uuid-1",60      "tenant_id": "tenant-uuid",61      "warehouse_id": "warehouse-uuid",62      "item_id": "item-uuid",63      "stock_id": "stock-uuid",64      "transaction_type": "initial_stock",65      "quantity": 100,66      "from_bin_id": null,67      "to_bin_id": "bin-uuid",68      "reference_type": "stock_action",69      "reference_id": null,70      "notes": "Initial stock via API",71      "performed_by": "user-uuid",72      "timestamp": "2023-06-15T09:45:00Z"73    }74  ]75}

Update Inventory Stock

Warehousing / Inventory Stock Management

PUT/warehousing/inventory-stock/:id

Updates an existing inventory stock record. Only provided fields will be updated (partial update). Validates that the stock record exists and belongs to the tenant before performing the update. Creates an audit transaction record for tracking changes.

• User must have 'manage:operations:tenant' permission

Business Rules

• Stock record must exist and belong to the specified tenant

• Only provided fields are updated (partial update supported)

• Quantity must be a non-negative number if provided

• Status must be one of: available, reserved, damaged, expired if provided

• An inventory transaction record is automatically created for audit trail

• Response includes list of fields that were actually changed

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the inventory stock record to update (required) UUID of the inventory stock record to update (required) Example: stock-uuid

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) UUID of the tenant (required if not in auth) Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
quantity	number	—
unit_of_measure	string	—
status	string	—
lot_number	string	—
serial_number	string	—
expiration_date	string	—
received_date	string	—
last_counted_at	string	—
notes	string	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/warehousing/inventory-stock/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "quantity": 150,6  "unit_of_measure": "ea",7  "status": "available",8  "lot_number": "LOT456",9  "serial_number": "SN789",10  "expiration_date": "2025-01-31T00:00:00Z",11  "received_date": "2023-07-01T00:00:00Z",12  "last_counted_at": "2023-07-15T14:30:00Z",13  "notes": "Stock updated after cycle count"14}'

Other request examples (1)

Request example 1

text

1{2  "quantity": number, // optional, non-negative3  "unit_of_measure": "string", // optional (e.g., "each", "box", "kg")4  "status": "string", // optional (available, reserved, damaged, expired)5  "lot_number": "string", // optional6  "serial_number": "string", // optional7  "expiration_date": "date", // optional8  "received_date": "date", // optional9  "last_counted_at": "date", // optional10  "notes": "string" // optional, used for transaction audit trail11}

Response examples

200 · Success Response404 · Error - Stock Not Found400 · Error - Stock ID Required400 · Error - Invalid Quantity400 · Error - Invalid Status404 · Error - Tenant Not Found403 · Error - Insufficient Permissions400 · Error - Invalid Request Body

200Success Response

Response body

json

1{2  "success": true,3  "message": "Inventory stock updated successfully",4  "stock": {5    "id": "stock-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "item_id": "item-uuid",9    "bin_id": "bin-uuid",10    "quantity": 150,11    "unit_of_measure": "ea",12    "status": "available",13    "lot_number": "LOT456",14    "serial_number": "SN789",15    "expiration_date": "2025-01-31T00:00:00Z",16    "received_date": "2023-07-01T00:00:00Z",17    "last_counted_at": "2023-07-15T14:30:00Z",18    "created_at": "2023-06-15T09:45:00Z",19    "updated_at": "2023-07-15T14:30:00Z",20    "item": {21      "id": "item-uuid",22      "name": "Test Product",23      "sku": "ITEM-001",24      "barcode": "123456789",25      "category": "Electronics",26      "subcategory": "Phones"27    },28    "bin": {29      "id": "bin-uuid",30      "name": "Bin A1",31      "code": "B-001",32      "location_type": "bin"33    },34    "warehouse": {35      "id": "warehouse-uuid",36      "name": "Main Warehouse",37      "code": "WH001"38    }39  },40  "changes": [41    "quantity",42    "lot_number",43    "serial_number",44    "expiration_date",45    "received_date",46    "last_counted_at"47  ]48}