Inventory Items Management
6 API calls in this section.
List Inventory Items
/warehousing/inventory-items?tenant_id={{tenant_id}}&warehouse_id=&brand=&search=&is_active=&category_ids=&page=1&limit=20Retrieves inventory items with comprehensive filtering options. Authentication: - Requires valid authentication token - User must have 'view:tenant' or 'manage:operations:tenant' permission Query Parameters: - tenant_id (required): UUID of the tenant - warehouse_id (optional): Filter by warehouse - brand (optional): Filter by brand - search (optional): Text search on name, SKU, or barcode - is_active (optional): Filter by active status (true or false) - category_ids (optional): Comma-separated list of category IDs (from warehouse_item_categories) to filter items by - page (optional): Page number for pagination (default: 1) - limit (optional): Number of items per page (default: 20) Response: - Returns a paginated list of inventory items - Each item includes categories as an array of { id, name } - Provides pagination information (total count, current page, limit)
1curl --request GET "$ONDI_BASE_URL/warehousing/inventory-items?tenant_id={{tenant_id}}&warehouse_id=&brand=&search=&is_active=&category_ids=&page=1&limit=20" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json"Query parameters
tenant_idOptional{{tenant_id}}
UUID of the tenant (required)
warehouse_idOptionalFilter by warehouse (optional)
brandOptionalFilter by brand (optional)
searchOptionalText search on name, SKU, or barcode (optional)
is_activeOptionalFilter by active status: true or false (optional)
category_idsOptionalComma-separated list of warehouse_item_categories IDs to filter by (optional)
pageOptional1
Page number for pagination (optional, default: 1)
limitOptional20
Number of items per page (optional, default: 20)
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "Inventory items retrieved successfully",4 "items": [5 {6 "id": "12345678-1234-1234-1234-123456789012",7 "name": "Wireless Headphones",8 "sku": "WH-200-BLK",9 "barcode": "INV1048",10 "description": "Premium noise-canceling wireless headphones",11 "brand": "SoundCore",12 "model": "Pro X",13 "unit_size": 1,14 "categories": [15 {16 "id": "category-uuid",17 "name": {18 "en": "Electronics"19 }20 },21 {22 "id": "nested-category-uuid",23 "name": {24 "en": "Headphones"25 }26 }27 ],28 "is_active": true,29 "updated_at": "2023-04-15T08:30:00Z"30 }31 ],32 "stats": {33 "total": 1,34 "active": 1,35 "inactive": 0,36 "labelPending": 0,37 "labelSuccess": 038 },39 "kpis": {40 "total": 1,41 "active": 1,42 "inactive": 0,43 "labelPending": 0,44 "labelSuccess": 045 },46 "page": 1,47 "limit": 20,48 "total": 149}1{2 "success": false,3 "message": "Tenant not found"4}1{2 "success": false,3 "message": "Insufficient permissions"4}1{2 "success": false,3 "message": "Internal server error"4}Create Inventory Item
/warehousing/inventory-items?tenant_id={{tenant_id}}Creates a new inventory item with detailed specifications and attributes. Supports adding comprehensive product information including dimensions, categories (via IDs), and custom attributes. Authentication: - Requires valid authentication token - User must have 'manage:operations:tenant' permission Query Parameters: - tenant_id (required): UUID of the tenant Business Rules: - Required fields: name, sku, and either unit_size or (weight and dimensions.length/width/height) - If unit_size is omitted, the system will compute it using tenant unit-size settings (volumetric/weight rules) based on the provided weight and dimensions - If item_code is provided, it must be a unique positive integer; otherwise the system generates the next available code from inventory_item_code_seq - When is_single_item is true, location_id is required and an inventory_stock row is created/updated at that bin with quantity = 1 - SKU must be unique within a tenant - Barcode is generated by the system as INV + item_code - Numeric values (unit_size, weight, dimensions) must be positive - is_active defaults to true if not specified
1curl --request POST "$ONDI_BASE_URL/warehousing/inventory-items?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "name": "Wireless Headphones",7 "sku": "WH-200-BLK",8 "item_code": 1048,9 "description": "Premium noise-canceling wireless headphones",10 "brand": "SoundCore",11 "model": "Pro X",12 "unit_size": 1,13 "weight": 0.35,14 "dimensions": {15 "length": 7.5,16 "width": 6.8,17 "height": 3.2,18 "unit": "inches"19 },20 "attributes": {21 "color": "black",22 "connectivity": "bluetooth",23 "battery_life": "24h"24 },25 "category_ids": [26 "{{category_id_1}}",27 "{{category_id_2}}"28 ],29 "is_single_item": true,30 "location_id": "{{bin_location_id}}",31 "is_active": true32}'1{2 "name": "Wireless Headphones",3 "sku": "WH-200-BLK",4 "item_code": 1048,5 "description": "Premium noise-canceling wireless headphones",6 "brand": "SoundCore",7 "model": "Pro X",8 "unit_size": 1,9 "weight": 0.35,10 "dimensions": {11 "length": 7.5,12 "width": 6.8,13 "height": 3.2,14 "unit": "inches"15 },16 "attributes": {17 "color": "black",18 "connectivity": "bluetooth",19 "battery_life": "24h"20 },21 "category_ids": [22 "{{category_id_1}}",23 "{{category_id_2}}"24 ],25 "is_single_item": true,26 "location_id": "{{bin_location_id}}",27 "is_active": true28}Query parameters
tenant_idOptional{{tenant_id}}
UUID of the tenant (required)
Request body fields
nameExampleExample field from the request body.
skuExampleExample field from the request body.
item_codeExampleExample field from the request body.
descriptionExampleExample field from the request body.
brandExampleExample field from the request body.
modelExampleExample field from the request body.
unit_sizeExampleExample field from the request body.
weightExampleExample field from the request body.
dimensionsExampleExample field from the request body.
dimensions.lengthExampleExample field from the request body.
dimensions.widthExampleExample field from the request body.
dimensions.heightExampleExample field from the request body.
dimensions.unitExampleExample field from the request body.
attributesExampleExample field from the request body.
attributes.colorExampleExample field from the request body.
attributes.connectivityExampleExample field from the request body.
attributes.battery_lifeExampleExample field from the request body.
category_idsExampleExample field from the request body.
is_single_itemExampleExample field from the request body.
location_idExampleExample field from the request body.
is_activeExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "Inventory item created successfully",4 "item": {5 "id": "12345678-1234-1234-1234-123456789012",6 "tenant_id": "tenant-uuid",7 "name": "Wireless Headphones",8 "sku": "WH-200-BLK",9 "item_code": 1048,10 "barcode": "INV1048",11 "description": "Premium noise-canceling wireless headphones",12 "brand": "SoundCore",13 "model": "Pro X",14 "unit_size": 1,15 "weight": 0.35,16 "dimensions": {17 "length": 7.5,18 "width": 6.8,19 "height": 3.2,20 "unit": "inches"21 },22 "attributes": {23 "color": "black",24 "connectivity": "bluetooth",25 "battery_life": "24h"26 },27 "category_ids": [28 "category-uuid",29 "nested-category-uuid"30 ],31 "category": {32 "id": "category-uuid",33 "name": {34 "en": "Electronics"35 },36 "parent_id": null37 },38 "sub_category": {39 "id": "nested-category-uuid",40 "name": {41 "en": "Headphones"42 },43 "parent_id": "category-uuid"44 },45 "categories": [46 {47 "id": "category-uuid",48 "name": {49 "en": "Electronics"50 }51 },52 {53 "id": "nested-category-uuid",54 "name": {55 "en": "Headphones"56 }57 }58 ],59 "is_active": true,60 "created_at": "2023-04-15T08:30:00Z",61 "updated_at": "2023-04-15T08:30:00Z"62 }63}1{2 "success": false,3 "message": "Field required: name"4}1{2 "success": false,3 "message": "Duplicate SKU"4}1{2 "success": false,3 "message": "Unit size must be a positive number"4}1{2 "success": false,3 "message": "Tenant not found"4}1{2 "success": false,3 "message": "Insufficient permissions"4}Get Inventory Item
/warehousing/inventory-items/:id?tenant_id={{tenant_id}}Retrieves a specific inventory item by its unique identifier. Includes detailed item information, category, sub category when applicable, and stock levels across warehouses. Authentication: - Requires valid authentication token - User must have 'view:tenant' or 'manage:operations:tenant' permission Path Parameters: - id: UUID of the inventory item (required) Query Parameters: - tenant_id: UUID of the tenant (required if not in auth) Response: - Returns detailed information about the specified inventory item - Includes linked category metadata in category_ids, category, sub_category, and categories - categories is returned as an array of { id, name } - Includes stock levels across different warehouses with bin locations
1curl --request GET "$ONDI_BASE_URL/warehousing/inventory-items/:id?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json"Path parameters
idRequireditem-uuid
UUID of the inventory item (required)
Query parameters
tenant_idOptional{{tenant_id}}
UUID of the tenant (required if not in auth)
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "Inventory item retrieved successfully",4 "item": {5 "id": "12345678-1234-1234-1234-123456789012",6 "tenant_id": "tenant-uuid",7 "name": "Wireless Headphones",8 "sku": "WH-200-BLK",9 "barcode": "INV1048",10 "description": "Premium noise-canceling wireless headphones",11 "brand": "SoundCore",12 "model": "Pro X",13 "unit_size": 1,14 "weight": 0.35,15 "dimensions": {16 "length": 7.5,17 "width": 6.8,18 "height": 3.2,19 "unit": "inches"20 },21 "attributes": {22 "color": "black",23 "connectivity": "bluetooth",24 "battery_life": "24h"25 },26 "category_ids": [27 "category-uuid",28 "nested-category-uuid"29 ],30 "category": {31 "id": "category-uuid",32 "name": {33 "en": "Electronics"34 },35 "parent_id": null36 },37 "sub_category": {38 "id": "nested-category-uuid",39 "name": {40 "en": "Headphones"41 },42 "parent_id": "category-uuid"43 },44 "categories": [45 {46 "id": "category-uuid",47 "name": {48 "en": "Electronics"49 }50 },51 {52 "id": "nested-category-uuid",53 "name": {54 "en": "Headphones"55 }56 }57 ],58 "is_active": true,59 "created_at": "2023-04-15T08:30:00Z",60 "updated_at": "2023-04-15T08:30:00Z"61 },62 "stock_levels": [63 {64 "id": "stock-uuid-1",65 "warehouse_id": "warehouse-uuid-1",66 "warehouse": {67 "id": "warehouse-uuid-1",68 "name": "Main Warehouse",69 "code": "WH001"70 },71 "bin_id": "bin-uuid-1",72 "bin": {73 "id": "bin-uuid-1",74 "code": "A-01-01",75 "name": "Section A, Shelf 1, Bin 1"76 },77 "quantity": 15,78 "status": "available",79 "lot_number": "LOT20230401",80 "expiration_date": "2025-04-01T00:00:00Z"81 }82 ],83 "outbound_delivery": {84 "id": "delivery-uuid",85 "delivery_code": "DEL1001",86 "customer_name": "John Doe",87 "status": "draft"88 },89 "inbound_delivery": null90}1{2 "success": false,3 "message": "Item not found"4}1{2 "success": false,3 "message": "Tenant not found"4}1{2 "success": false,3 "message": "Insufficient permissions"4}Get Inventory Item By Code
/warehousing/inventory-items/code/:item_code?tenant_id={{tenant_id}}Retrieves an inventory item by numeric item_code. Excludes label fields and enriches with delivery summary, receiving order, stock details, category, sub category, and categories when applicable. categories is returned as an array of { id, name }.
1curl --request GET "$ONDI_BASE_URL/warehousing/inventory-items/code/:item_code?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json"Path parameters
item_codeRequired1048
Numeric item code
Query parameters
tenant_idOptional{{tenant_id}}
UUID of the tenant (required if not in auth)
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "Inventory item retrieved successfully",4 "item": {5 "id": "item-uuid",6 "tenant_id": "tenant-uuid",7 "sku": "PKG-1756815438880",8 "name": "Garbalia Black Unisex Wallet",9 "unit_size": "1.00",10 "category_ids": [11 "category-uuid",12 "nested-category-uuid"13 ],14 "category": {15 "id": "category-uuid",16 "name": {17 "en": "Accessories"18 },19 "parent_id": null20 },21 "sub_category": {22 "id": "nested-category-uuid",23 "name": {24 "en": "Wallets"25 },26 "parent_id": "category-uuid"27 },28 "categories": [29 {30 "id": "category-uuid",31 "name": {32 "en": "Accessories"33 }34 },35 {36 "id": "nested-category-uuid",37 "name": {38 "en": "Wallets"39 }40 }41 ],42 "is_active": true,43 "item_code": 1048,44 "barcode": "INV1048"45 },46 "outbound_delivery": {47 "id": "delivery-uuid",48 "delivery_code": "DEL1001",49 "customer_name": "John Doe",50 "pickup_full_address": "Pickup address...",51 "dropoff_full_address": "Dropoff address...",52 "status": "draft"53 },54 "inbound_delivery": null,55 "receiving_order": {56 "id": "ro-uuid",57 "reference_number": "RO-0001",58 "status": "pending",59 "warehouse": {60 "name": "Main Warehouse",61 "code": "WH001"62 },63 "item_details": [64 {65 "item_id": "item-uuid",66 "quantity": 167 }68 ]69 },70 "stock": [71 {72 "id": "stock-uuid",73 "quantity": 5,74 "reserved_quantity": 0,75 "status": "available",76 "warehouse": {77 "id": "wh-uuid",78 "name": "Main Warehouse",79 "code": "WH001"80 },81 "bin": {82 "id": "bin-uuid",83 "code": "A-01-01",84 "name": "Section A, Shelf 1, Bin 1"85 }86 }87 ]88}1{2 "success": false,3 "message": "Item not found"4}Update Inventory Item
/warehousing/inventory-items/:id?tenant_id={{tenant_id}}Updates an existing inventory item with new details. Only the provided fields will be updated, while others remain unchanged. Authentication: - Requires valid authentication token - User must have 'manage:operations:tenant' permission Path Parameters: - id: UUID of the inventory item to update (required) Query Parameters: - tenant_id: UUID of the tenant (required if not in auth) Business Rules: - At least one field must be provided for update - If providing SKU, it must be unique within the tenant - Unknown/forbidden fields are rejected with 400 (error: forbidden_fields_present) - If no valid fields provided, 400 (error: no_valid_fields_to_update) - Numeric values (unit_size, weight, dimensions) must be positive if provided
1curl --request PATCH "$ONDI_BASE_URL/warehousing/inventory-items/:id?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "name": "Wireless Headphones Pro",7 "description": "Updated description for premium noise-canceling wireless headphones",8 "brand": "SoundCore Pro",9 "dimensions": {10 "length": 7.5,11 "width": 6.8,12 "height": 3.2,13 "unit": "inches"14 },15 "attributes": {16 "color": "black",17 "connectivity": "bluetooth 5.0",18 "battery_life": "30h"19 },20 "category_ids": [21 "{{category_id_1}}",22 "{{category_id_2}}"23 ],24 "is_active": true25}'1{2 "name": "Wireless Headphones Pro",3 "description": "Updated description for premium noise-canceling wireless headphones",4 "brand": "SoundCore Pro",5 "dimensions": {6 "length": 7.5,7 "width": 6.8,8 "height": 3.2,9 "unit": "inches"10 },11 "attributes": {12 "color": "black",13 "connectivity": "bluetooth 5.0",14 "battery_life": "30h"15 },16 "category_ids": [17 "{{category_id_1}}",18 "{{category_id_2}}"19 ],20 "is_active": true21}Path parameters
idRequireditem-uuid
UUID of the inventory item to update (required)
Query parameters
tenant_idOptional{{tenant_id}}
UUID of the tenant (required if not in auth)
Request body fields
nameExampleExample field from the request body.
descriptionExampleExample field from the request body.
brandExampleExample field from the request body.
dimensionsExampleExample field from the request body.
dimensions.lengthExampleExample field from the request body.
dimensions.widthExampleExample field from the request body.
dimensions.heightExampleExample field from the request body.
dimensions.unitExampleExample field from the request body.
attributesExampleExample field from the request body.
attributes.colorExampleExample field from the request body.
attributes.connectivityExampleExample field from the request body.
attributes.battery_lifeExampleExample field from the request body.
category_idsExampleExample field from the request body.
is_activeExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "Inventory item updated successfully",4 "item": {5 "id": "12345678-1234-1234-1234-123456789012",6 "tenant_id": "tenant-uuid",7 "name": "Wireless Headphones Pro",8 "sku": "WH-200-BLK",9 "barcode": "INV1048",10 "description": "Updated description for premium noise-canceling wireless headphones",11 "brand": "SoundCore Pro",12 "model": "Pro X",13 "unit_size": 1,14 "weight": 0.35,15 "dimensions": {16 "length": 7.5,17 "width": 6.8,18 "height": 3.2,19 "unit": "inches"20 },21 "attributes": {22 "color": "black",23 "connectivity": "bluetooth 5.0",24 "battery_life": "30h"25 },26 "category_ids": [27 "category-uuid",28 "nested-category-uuid"29 ],30 "category": {31 "id": "category-uuid",32 "name": {33 "en": "Electronics"34 },35 "parent_id": null36 },37 "sub_category": {38 "id": "nested-category-uuid",39 "name": {40 "en": "Headphones"41 },42 "parent_id": "category-uuid"43 },44 "categories": [45 {46 "id": "category-uuid",47 "name": {48 "en": "Electronics"49 }50 },51 {52 "id": "nested-category-uuid",53 "name": {54 "en": "Headphones"55 }56 }57 ],58 "is_active": true,59 "created_at": "2023-04-15T08:30:00Z",60 "updated_at": "2023-04-20T10:15:00Z"61 }62}1{2 "success": false,3 "message": "Item not found"4}1{2 "success": false,3 "message": "Duplicate SKU"4}1{2 "success": false,3 "message": "Invalid request body",4 "error": "forbidden_fields_present",5 "fields": [6 "barcode"7 ]8}1{2 "success": false,3 "message": "Invalid request body",4 "error": "no_valid_fields_to_update"5}1{2 "success": false,3 "message": "Unit size must be a positive number"4}1{2 "success": false,3 "message": "Tenant not found"4}1{2 "success": false,3 "message": "Insufficient permissions"4}Execute Delivery from Inventory Item
/warehousing/inventory-items/:id/execute-delivery?tenant_id={{tenant_id}}Executes a delivery for an inventory item. Optionally receives the item first if a bin_id is provided. Authentication: - Requires valid authentication token - User must have 'manage:operations:tenant' permission Path Parameters: - id: UUID of the inventory item (required) Query Parameters: - tenant_id: UUID of the tenant (required if not in auth context) Behavior when bin_id is provided: - Fetch receiving order for the item via RPC - If receiving order status is 'received', return error 'item already received' - Otherwise, receive the item to the provided bin (updates inventory_stock) - Then proceed to execute delivery as usual Business Rules: 1. Item must have an associated delivery_id 2. Delivery status must be 'draft' 3. Item must exist in inventory stock within the same warehouse (for delivery) 4. Updates delivery status from 'draft' to 'pending' 5. Updates stock quantity to 0 and reserved_quantity to actual quantity 6. Creates a picking order with 'completed' status 7. Creates a handoff in 'pending' status Process Flow: - Validates item has delivery assigned - Optionally receives to bin - Checks delivery is in draft status - Verifies item exists in stock - Updates delivery status to pending - Reserves stock quantity - Creates auto-completed picking order - Creates pending handoff record
1curl --request POST "$ONDI_BASE_URL/warehousing/inventory-items/:id/execute-delivery?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "bin_id": "{{bin_id}}"7}'1{2 "bin_id": "{{bin_id}}"3}Path parameters
idRequireditem-uuid
UUID of the inventory item (required)
Query parameters
tenant_idOptional{{tenant_id}}
UUID of the tenant (required if not in auth)
Request body fields
bin_idExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "Delivery executed successfully from item",4 "inventory_item": {5 "id": "item-uuid",6 "name": "Product Name",7 "sku": "SKU-123",8 "delivery_id": "delivery-uuid"9 },10 "delivery": {11 "id": "delivery-uuid",12 "status": "pending"13 },14 "stock_update": {15 "previous_quantity": 5,16 "new_quantity": 0,17 "reserved_quantity": 518 },19 "picking_order": {20 "id": "picking-order-uuid",21 "reference_number": "PKO-1234567890",22 "status": "completed"23 },24 "handoff": {25 "id": "handoff-uuid",26 "status": "pending"27 }28}1{2 "success": false,3 "message": "Item not found"4}1{2 "success": false,3 "message": "Item has no delivery assigned"4}1{2 "success": false,3 "message": "Delivery status must be draft"4}1{2 "success": false,3 "message": "Item not found in inventory stock"4}1{2 "success": false,3 "message": "Insufficient permissions"4}