Inventory Items Management

7 API calls in this section.

Endpoints for managing inventory items in the warehouse management system. These APIs provide CRUD operations for item master data with support for detailed specifications, categorization, and stock tracking across warehouses.

List Inventory Items

Warehousing / Inventory Items Management

GET/warehousing/inventory-items

Retrieves inventory items with comprehensive filtering options.

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

Business Rules

• With warehouse_id, every item returns stock_quantity from the transactionally maintained warehouse-item total.

• stock_status is in_stock only when stock_quantity > 0; zero returns depleted.

• Without warehouse_id, both stock fields are null because stock state is warehouse-specific.

• is_active is item activation and does not determine stock status.

Frontend integration contract

• Send the currently selected warehouse ID as warehouse_id.

• Render the stock badge from items[].stock_status and quantity from items[].stock_quantity; do not derive stock from is_active.

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)

Query parameters

Parameter	Type	Description
tenant_idRequired	string	UUID of the tenant (required) UUID of the tenant (required) Example: {{tenant_id}}
warehouse_idOptional	string	Filter by warehouse (optional) Filter by warehouse and populate warehouse-specific stock fields Filter by warehouse (optional) Filter by warehouse and populate warehouse-specific stock fields
brandOptional	string	Filter by brand (optional) Filter by brand (optional)
searchOptional	string	Text search on name, SKU, or barcode (optional) Text search on name, SKU, or barcode (optional)
is_activeOptional	string	Filter by active status: true or false (optional) Filter by active status (true or false) Filter by active status: true or false (optional) Filter by active status (true or false)
category_idsOptional	string	Comma-separated list of warehouse_item_categories IDs to filter by (optional) Comma-separated list of category IDs (from warehouse_item_categories) to filter items by Comma-separated list of warehouse_item_categories IDs to filter by (optional) Comma-separated list of category IDs (from warehouse_item_categories) to filter items by
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-items?tenant_id=${TENANT_ID}&warehouse_id=&brand=&search=&is_active=&category_ids=&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 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      "stock_quantity": 0,15      "stock_status": "depleted",16      "categories": [17        {18          "id": "category-uuid",19          "name": {20            "en": "Electronics"21          }22        },23        {24          "id": "nested-category-uuid",25          "name": {26            "en": "Headphones"27          }28        }29      ],30      "is_active": true,31      "updated_at": "2023-04-15T08:30:00Z"32    }33  ],34  "stats": {35    "total": 1,36    "active": 1,37    "inactive": 0,38    "labelPending": 0,39    "labelSuccess": 040  },41  "kpis": {42    "total": 1,43    "active": 1,44    "inactive": 0,45    "labelPending": 0,46    "labelSuccess": 047  },48  "page": 1,49  "limit": 20,50  "total": 151}

Create Inventory Item

Warehousing / Inventory Items Management

POST/warehousing/inventory-items

Creates a new inventory item with detailed specifications and attributes. Supports adding comprehensive product information including dimensions, categories (via IDs), and custom attributes.

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

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 allocates the next sequence code not already in use. Manual item codes remain supported, and concurrent manual/automatic claims for the same code are serialized

• 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

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
name	string	—
sku	string	—
item_code	number	—
description	string	—
brand	string	—
model	string	—
unit_size	number	—
weight	number	—
dimensions	object	—
dimensions.length	number	—
dimensions.width	number	—
dimensions.height	number	—

Show 9 more body fields

Additional body parameters

Parameter	Type	Description
dimensions.unit	string	—
attributes	object	—
attributes.color	string	—
attributes.connectivity	string	—
attributes.battery_life	string	—
category_ids	array<string>	—
is_single_item	boolean	—
location_id	string	—
is_active	boolean	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/warehousing/inventory-items?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": "Wireless Headphones",6  "sku": "WH-200-BLK",7  "item_code": 1048,8  "description": "Premium noise-canceling wireless headphones",9  "brand": "SoundCore",10  "model": "Pro X",11  "unit_size": 1,12  "weight": 0.35,13  "dimensions": {14    "length": 7.5,15    "width": 6.8,16    "height": 3.2,17    "unit": "inches"18  },19  "attributes": {20    "color": "black",21    "connectivity": "bluetooth",22    "battery_life": "24h"23  },24  "category_ids": [25    "{{category_id_1}}",26    "{{category_id_2}}"27  ],28  "is_single_item": true,29  "location_id": "{{bin_location_id}}",30  "is_active": true31}'

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

Other request examples (1)

Request example 1

text

1{2  "name": "string", // required3  "sku": "string", // required, must be unique within tenant4  "item_code": number, // optional, positive integer; if omitted, allocated from the sequence while skipping codes already claimed manually5  "description": "string", // optional6  "brand": "string", // optional7  "model": "string", // optional8  "unit_size": number, // optional, must be positive; if omitted, weight + dimensions are required9  "weight": number, // optional, must be positive10  "dimensions": { // optional11    "length": number, // must be positive12    "width": number, // must be positive13    "height": number, // must be positive14    "unit": "string" // unit of measurement (must match tenant dimension unit settings)15  },16  "attributes": { // optional17    "color": "string",18    "size": "string",19    "material": "string",20    "custom_attributes": {21      "key1": "value1",22      "key2": "value2"23    }24  },25  "category_ids": ["uuid", "uuid"], // optional, link to warehouse_item_categories26  "is_single_item": boolean, // optional; when true, a single stock record is created27  "location_id": "uuid", // required if is_single_item is true; warehouse location/bin id28  "is_active": boolean // optional, defaults to true29}

Response examples

201 · Success Response400 · Error - Missing Required Field400 · Error - Duplicate SKU400 · Error - Invalid Unit Size404 · Error - Tenant Not Found403 · Error - Insufficient Permissions

201Success Response

Response body

json

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}

Get Inventory Item

Warehousing / Inventory Items Management

GET/warehousing/inventory-items/:id

Retrieves a specific inventory item by its unique identifier.

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

Business Rules

• A warehouse-scoped request never returns stock from another warehouse.

• If the item has no stock record in the selected warehouse, stock_levels is an empty array.

• A zero-quantity stock record remains in stock_levels with its actual quantity and status.

• Omitting warehouse_id preserves the existing cross-warehouse detail response for non-warehouse clients.

Frontend integration contract

• The warehouse app must send its currently selected warehouse as literal warehouse_id.

• Calculate the top-card quantity only from the returned stock_levels; do not reuse stock from another request or warehouse.

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 only the requested warehouse's stock levels when warehouse_id is supplied

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the inventory item (required) UUID of the inventory item (required) Example: item-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}}
warehouse_idOptional	string	Selected warehouse UUID; limits stock_levels to this warehouse Selected warehouse UUID (optional). When supplied, stock_levels contains records only from that warehouse. Selected warehouse UUID; limits stock_levels to this warehouse Selected warehouse UUID (optional). When supplied, stock_levels contains records only from that warehouse. Example: {{warehouse_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-items/${ID}?tenant_id=${TENANT_ID}&warehouse_id=${WAREHOUSE_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200 · Success Response404 · Error - Item Not Found404 · Error - Tenant Not Found403 · Error - Insufficient Permissions

200Success Response

Response body

json

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}

Get Inventory Item By Code

Warehousing / Inventory Items Management

GET/warehousing/inventory-items/code/:item_code

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 }.

Path parameters

Parameter	Type	Description
item_codeRequired	string	Numeric item code Numeric item code Example: 1048

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-items/code/${ITEM_CODE}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200 · Success Response404 · Error - Item Not Found

200Success Response

Response body

json

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}

Update Inventory Item

Warehousing / Inventory Items Management

PATCH/warehousing/inventory-items/:id

Updates an existing inventory item with new details. Only the provided fields will be updated, while others remain unchanged.

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

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

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the inventory item to update (required) UUID of the inventory item to update (required) Example: item-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
name	string	—
description	string	—
brand	string	—
dimensions	object	—
dimensions.length	number	—
dimensions.width	number	—
dimensions.height	number	—
dimensions.unit	string	—
attributes	object	—
attributes.color	string	—
attributes.connectivity	string	—
attributes.battery_life	string	—

Show 2 more body fields

Additional body parameters

Parameter	Type	Description
category_ids	array<string>	—
is_active	boolean	—

Staging

Request

curl

1curl --globoff --request PATCH "https://staging-api.ondi.io/functions/v1/warehousing/inventory-items/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": "Wireless Headphones Pro",6  "description": "Updated description for premium noise-canceling wireless headphones",7  "brand": "SoundCore Pro",8  "dimensions": {9    "length": 7.5,10    "width": 6.8,11    "height": 3.2,12    "unit": "inches"13  },14  "attributes": {15    "color": "black",16    "connectivity": "bluetooth 5.0",17    "battery_life": "30h"18  },19  "category_ids": [20    "{{category_id_1}}",21    "{{category_id_2}}"22  ],23  "is_active": true24}'

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

Other request examples (1)

Request example 1

text

1{2  "name": "string", // optional3  "sku": "string", // optional, must be unique within tenant4  "description": "string", // optional5  "brand": "string", // optional6  "model": "string", // optional7  "unit_size": number, // optional, must be positive8  "weight": number, // optional, must be positive9  "dimensions": { // optional10    "length": number, // must be positive11    "width": number, // must be positive12    "height": number, // must be positive13    "unit": "string" // unit of measurement14  },15  "attributes": { // optional16    "color": "string",17    "size": "string",18    "material": "string",19    "custom_attributes": {20      "key1": "value1",21      "key2": "value2"22    }23  },24  "category_ids": ["uuid", "uuid"], // optional, replaces existing category links25  "is_active": boolean // optional26}

Response examples

200 · Success Response404 · Error - Item Not Found400 · Error - Duplicate SKU400 · Error - Forbidden Fields Present400 · Error - No Valid Fields To Update400 · Error - Invalid Unit Size404 · Error - Tenant Not Found403 · Error - Insufficient Permissions

200Success Response

Response body

json

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}

Execute Delivery from Inventory Item

Warehousing / Inventory Items Management

POST/warehousing/inventory-items/:id/execute-delivery

Executes a delivery for an inventory item in one explicit warehouse. Optionally receives the item first if bin_id is provided.

• The actor must have an active warehouse_staff assignment for warehouse_id.

Business Rules

• The requested warehouse must be the delivery's current warehouse.

• Only positive available stock in that exact warehouse can be prepared.

• The delivery must be draft.

• For a warehouse-staged P&D or operational-return order, success keeps stock quantity in the warehouse, reserves it, creates one completed picking order, and returns handoff: null. Assignment creates the handoff later with driver context.

• Existing non-P&D execution creates a pending handoff and returns its object, including handoff.id and handoff.status.

• HTTP 403 warehouse_access_denied means the actor is not active staff of the requested warehouse.

• HTTP 409 receiving_order_not_current_warehouse means custody belongs to another warehouse.

Frontend integration contract

• Send the warehouse currently open in the warehouse app as literal warehouse_id.

• For a P&D success, treat handoff: null as prepared and waiting for assignment, not as an error.

• Do not retry with a different warehouse inferred from the response.

• Hide/disable Execute after either custody conflict, and show the localized backend message.

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the inventory item (required). UUID of the inventory item (required). Example: item-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
warehouse_idRequired	string	is required. is required.
bin_idOptional	string	is optional. is optional.

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/warehousing/inventory-items/${ID}/execute-delivery?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  "bin_id": "{{bin_id}}"7}'

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

Other request examples (1)

Request example 1

json

1{2  "warehouse_id": "warehouse-uuid",3  "bin_id": "bin-uuid"4}

Response examples

200 · Success Response404 · Error - Item Not Found400 · Error - No Delivery Assigned400 · Error - Delivery Status Must Be Draft404 · Error - Item Not Found in Stock409 · Error - Parent Exception Open403 · Error - Warehouse Access Denied500 · Wallet Error Contract - Warehouse Execution

200Success Response

Response body

json

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": 5,17    "reserved_quantity": 518  },19  "picking_order": {20    "id": "picking-order-uuid",21    "reference_number": "PKO-1234567890",22    "status": "completed"23  },24  "handoff": null25}

Execute Deliveries from Inventory Items

Warehousing / Inventory Items Management

POST/warehousing/inventory-items/execute-deliveries

Executes outbound deliveries for multiple inventory items in one explicit warehouse.

• The actor must have an active warehouse_staff assignment for warehouse_id. Access is checked once for the batch.

Business Rules

• Every item is scoped to positive available stock in the requested warehouse.

• Every delivery must currently belong to the requested warehouse and be draft.

• Warehouse-staged P&D and operational-return rows are prepared in one set-based call: stock quantity stays in the warehouse and becomes reserved, one completed pick is created per delivery, and each result returns handoff: null.

• Existing non-P&D execution creates a pending handoff and returns its object, including handoff.id and handoff.status, in that item result.

• Duplicate item IDs are skipped with duplicate_item_id.

Frontend integration contract

• Send the warehouse currently open in the warehouse app as literal warehouse_id.

• Use executed_count, failed_count, and results[] for item results.

• For a P&D success, treat handoff: null as prepared and waiting for assignment.

• Treat top-level HTTP 403 warehouse_access_denied as a warehouse authorization failure, not an item failure.

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
warehouse_id	string	—
item_idsRequired	array<string>	are required. are required.
bin_idOptional	string	is optional. is optional.

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/warehousing/inventory-items/execute-deliveries?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_ids": [7    "item-uuid-1",8    "item-uuid-2"9  ],10  "bin_id": "{{bin_id}}"11}'

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

Other request examples (1)

Request example 1

json

1{2  "warehouse_id": "warehouse-uuid",3  "item_ids": [4    "item-uuid-1",5    "item-uuid-2"6  ],7  "bin_id": "bin-uuid"8}

Response examples

200 · Success - Non-P&D Execution With Handoff200 · Success - Partial or Full Batch400 · Error - No Items Executed400 · Wallet Error Contract - Warehouse Bulk Execution

200Success - Non-P&D Execution With Handoff

Response body

json

1{2  "success": true,3  "message": "Some item deliveries executed successfully",4  "executed_count": 1,5  "failed_count": 1,6  "results": [7    {8      "item_id": "item-uuid-1",9      "success": true,10      "status": 200,11      "message": "Delivery executed successfully from item",12      "inventory_item": {13        "id": "item-uuid-1",14        "name": "Product Name",15        "sku": "SKU-123",16        "outbound_delivery_id": "delivery-uuid-1"17      },18      "delivery": {19        "id": "delivery-uuid-1",20        "status": "pending"21      },22      "stock_update": {23        "previous_quantity": 1,24        "new_quantity": 0,25        "reserved_quantity": 126      },27      "picking_order": {28        "id": "picking-order-uuid",29        "status": "completed"30      },31      "handoff": {32        "id": "handoff-uuid",33        "status": "pending"34      }35    },36    {37      "item_id": "item-uuid-2",38      "success": false,39      "status": 400,40      "message": "Delivery status must be draft"41    }42  ]43}