Picking Orders

4 API calls in this section.

Endpoints for managing picking orders, which represent instructions to retrieve items from inventory for shipment, transfer, or internal use. Supports creating orders, assigning them to staff, and tracking their fulfillment status.

List Picking Orders

Warehousing / Picking Orders

GET/warehousing/picking-orders

Retrieves a list of picking orders with filtering options. Supports pagination and provides metadata for available filter options.

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

Response

• Returns a paginated list of picking orders with detailed item information

• Includes information about the creating user and assigned user

• Includes stats and status_matrix status counts scoped to the tenant and to warehouse_id when a warehouse filter is provided; status itself is not applied to these counts so the UI can render status tabs for the selected warehouse

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

Frontend integration contract

• When calling this endpoint with warehouse_id, use status_matrix/stats as the counts for that selected warehouse only.

• Use total for the current result set after all filters, including status.

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant Example: {{tenant_id}}
warehouse_idOptional	string	Filter by specific warehouse UUID (optional) Filter by specific warehouse UUID (optional)
statusOptional	string	Filter by order status: pending, in_progress, completed, cancelled (optional) Filter by order status (e.g., pending, in_progress, completed, handed_off, cancelled) Filter by order status: pending, in_progress, completed, cancelled (optional) Filter by order status (e.g., pending, in_progress, completed, handed_off, cancelled)
order_typeOptional	string	Filter by order type: individual, batch, waybill (optional) Filter by order type (e.g., individual, batch, waybill) Filter by order type: individual, batch, waybill (optional) Filter by order type (e.g., individual, batch, waybill)
priorityOptional	string	Sort by priority: asc or desc (optional) Filter by priority level (numeric value) Sort by priority: asc or desc (optional) Filter by priority level (numeric value)
completedOptional	string	Filter by completion status: true (completed), false (not completed) (optional) Filter by completion status: true (completed), false (not completed) (optional)
searchOptional	string	Search by reference number (case insensitive) (optional) Search by reference number (case insensitive) (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, max: 100) Number of items per page (default: 20) Number of items per page (optional, default: 20, max: 100) 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/picking-orders?tenant_id=${TENANT_ID}&warehouse_id=&status=&order_type=&priority=&completed=&search=&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": "Picking orders retrieved successfully",4  "orders": [5    {6      "id": "01234567-89ab-cdef-0123-456789abcdef",7      "tenant_id": "f6a1b2c3-d4e5-4321-8901-f1234567890a",8      "warehouse_id": "w1e2f3a4-b5c6-7890-1234-56789abcdef0",9      "reference_number": "PKO-00001",10      "external_reference": "ORD-2024-001",11      "order_type": "individual",12      "priority": 1,13      "status": "pending",14      "due_date": "2024-01-15T10:00:00Z",15      "completed_date": null,16      "item_details": [17        {18          "item_id": "i1e2f3a4-b5c6-7890-1234-56789abcdef0",19          "bin_id": "l1e2f3a4-b5c6-7890-1234-56789abcdef0",20          "quantity": 10,21          "picked_quantity": 0,22          "status": "pending"23        }24      ],25      "picking_progress": {26        "total_items": 10,27        "picked_items": 0,28        "start_time": null,29        "end_time": null,30        "picker_notes": ""31      },32      "notes": "Express shipment for VIP customer",33      "assigned_to": "u1e2f3a4-b5c6-7890-1234-56789abcdef0",34      "created_by": "admin-uuid-1234",35      "created_at": "2024-01-10T10:00:00Z",36      "updated_at": "2024-01-10T10:00:00Z",37      "created_by_user": {38        "id": "admin-uuid-1234",39        "full_name": "Admin User"40      },41      "assigned_to_user": {42        "id": "u1e2f3a4-b5c6-7890-1234-56789abcdef0",43        "full_name": "John Picker"44      },45      "warehouse": {46        "id": "w1e2f3a4-b5c6-7890-1234-56789abcdef0",47        "name": "Main Warehouse",48        "code": "WH001"49      }50    }51  ],52  "stats": {53    "pending": 1,54    "in_progress": 0,55    "completed": 0,56    "handed_off": 0,57    "cancelled": 0,58    "total": 159  },60  "status_matrix": {61    "pending": 1,62    "in_progress": 0,63    "completed": 0,64    "handed_off": 0,65    "cancelled": 0,66    "total": 167  },68  "page": 1,69  "limit": 20,70  "total": 171}

Create Picking Order

Warehousing / Picking Orders

POST/warehousing/picking-orders

Creates a new picking order with items to be retrieved from inventory. The endpoint performs extensive validation including warehouse existence, item availability, bin locations, and stock quantity.

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

Business Rules

• Warehouse must exist and belong to the specified tenant

• Each item must exist in inventory and be stored in the specified bin

• Requested quantity is calculated only from unreserved stock rows with literal status=available and quantity>0

• A stock row depleted by a warehouse-exception write-off cannot be offered, picked, or newly reserved

• If assigned_to is provided, user must exist and be a member of the tenant

• Reference number is auto-generated if not provided (format: PKO-XXXXX)

• Order type must be one of: individual, batch, waybill

• Status must be one of: pending, in_progress, completed, cancelled

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant 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	—
reference_number	string	—
external_reference	string	—
order_type	string	—
priority	number	—
status	string	—
item_details	array<object>	—
item_details.item_id	string	—
item_details.bin_id	string	—
item_details.quantity	number	—
item_details.picked_quantity	number	—
item_details.status	string	—

Show 9 more body fields

Additional body parameters

Parameter	Type	Description
picking_progress	object	—
picking_progress.total_items	number	—
picking_progress.picked_items	number	—
picking_progress.start_time	null	—
picking_progress.end_time	null	—
picking_progress.picker_notes	string	—
notes	string	—
assigned_to	string	—
due_date	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/warehousing/picking-orders?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  "reference_number": "PKO-00012",7  "external_reference": "EXT-12345",8  "order_type": "individual",9  "priority": 1,10  "status": "pending",11  "item_details": [12    {13      "item_id": "{{item_id_1}}",14      "bin_id": "{{bin_id_1}}",15      "quantity": 10,16      "picked_quantity": 0,17      "status": "pending"18    },19    {20      "item_id": "{{item_id_2}}",21      "bin_id": "{{bin_id_2}}",22      "quantity": 5,23      "picked_quantity": 0,24      "status": "pending"25    }26  ],27  "picking_progress": {28    "total_items": 15,29    "picked_items": 0,30    "start_time": null,31    "end_time": null,32    "picker_notes": ""33  },34  "notes": "Express shipment for VIP customer",35  "assigned_to": "{{user_id}}",36  "due_date": "2023-07-01T10:00:00Z"37}'

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

Other request examples (1)

Request example 1

text

1{2  "warehouse_id": "uuid", // required3  "order_type": "string", // required (individual, batch, waybill)4  "status": "string", // required (pending, in_progress, completed, cancelled)5  "item_details": [ // required array6    {7      "item_id": "uuid", // required8      "bin_id": "uuid", // required9      "quantity": number, // required, must be positive10      "picked_quantity": number, // optional, defaults to 011      "status": "string" // optional, defaults to "pending"12    }13  ],14  "reference_number": "string", // optional, auto-generated if not provided15  "external_reference": "string", // optional (e.g., source system reference)16  "priority": number, // optional, defaults to 017  "picking_progress": { // optional18    "total_items": number,19    "picked_items": number,20    "start_time": "timestamp",21    "end_time": "timestamp",22    "picker_notes": "string"23  },24  "notes": "string", // optional25  "assigned_to": "uuid", // optional, user ID to assign the order to26  "due_date": "timestamp" // optional27}

Response examples

201 · Success Response400 · Error - Missing Required Field400 · Error - Invalid Order Type400 · Error - Invalid Status400 · Error - Invalid Item Details400 · Error - Missing Item Fields400 · Error - Invalid Quantity400 · Error - Insufficient Stock404 · Error - Item Not Found404 · Error - Item Not In Bin404 · Error - Bin Not Found404 · Error - Warehouse Not Found404 · Error - Assigned User Not Found404 · Error - Tenant Not Found403 · Error - Insufficient Permissions500 · Error - Server Error

201Success Response

Response body

json

1{2  "success": true,3  "message": "Picking order created successfully",4  "order": {5    "id": "order-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "reference_number": "PKO-00012",9    "external_reference": "EXT-12345",10    "order_type": "individual",11    "priority": 1,12    "status": "pending",13    "item_details": [14      {15        "item_id": "item-uuid-1",16        "bin_id": "bin-uuid-1",17        "quantity": 10,18        "picked_quantity": 0,19        "status": "pending"20      },21      {22        "item_id": "item-uuid-2",23        "bin_id": "bin-uuid-2",24        "quantity": 5,25        "picked_quantity": 0,26        "status": "pending"27      }28    ],29    "picking_progress": {30      "total_items": 15,31      "picked_items": 0,32      "start_time": null,33      "end_time": null,34      "picker_notes": ""35    },36    "notes": "Express shipment for VIP customer",37    "assigned_to": "user-uuid",38    "due_date": "2023-07-01T10:00:00Z",39    "created_by": "admin-uuid",40    "created_at": "2023-06-01T10:00:00Z",41    "updated_at": "2023-06-01T10:00:00Z"42  }43}

Get Picking Order

Warehousing / Picking Orders

GET/warehousing/picking-orders/:id

Retrieves detailed information about a specific picking order by its ID, including warehouse, creator, and assignee details.

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

Response

• Returns comprehensive picking order details

• Includes associated warehouse information

• Includes information about the creator and assigned user

• Provides detailed item specifications with quantities

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the picking order to retrieve (required) UUID of the picking order to retrieve (required)

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant 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/picking-orders/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200 · Success Response400 · Error - Order ID Required404 · Error - Order Not Found404 · Error - Tenant Not Found403 · Error - Insufficient Permissions500 · Error - Server Error

200Success Response

Response body

json

1{2  "success": true,3  "message": "Picking order retrieved successfully",4  "order": {5    "id": "order-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "reference_number": "PKO-00012",9    "external_reference": "EXT-12345",10    "order_type": "individual",11    "priority": 1,12    "status": "pending",13    "item_details": [14      {15        "item_id": "item-uuid-1",16        "bin_id": "bin-uuid-1",17        "quantity": 10,18        "picked_quantity": 0,19        "status": "pending"20      },21      {22        "item_id": "item-uuid-2",23        "bin_id": "bin-uuid-2",24        "quantity": 5,25        "picked_quantity": 0,26        "status": "pending"27      }28    ],29    "picking_progress": {30      "total_items": 15,31      "picked_items": 0,32      "start_time": null,33      "end_time": null,34      "picker_notes": ""35    },36    "notes": "Express shipment for VIP customer",37    "assigned_to": "user-uuid",38    "due_date": "2023-07-01T10:00:00Z",39    "created_by": "admin-uuid",40    "created_at": "2023-06-01T10:00:00Z",41    "updated_at": "2023-06-01T10:00:00Z",42    "warehouse": {43      "id": "warehouse-uuid",44      "name": "Main Warehouse",45      "code": "WH001"46    },47    "created_by_user": {48      "id": "admin-uuid",49      "first_name": "Admin",50      "last_name": "User",51      "email": "[email protected]"52    },53    "assigned_to_user": {54      "id": "user-uuid",55      "first_name": "John",56      "last_name": "Picker",57      "email": "[email protected]"58    }59  }60}

Update Picking Order

Warehousing / Picking Orders

PUT/warehousing/picking-orders/:id

Updates the status and assignee of a specific picking order.

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

Business Rules

• Warehouse stock validation and the existing status rules remain unchanged.

• delivery_id marks a lifecycle-managed P&D/operational-return picking cycle. Do not send status=handed_off for that record; the assigned driver's Pickup action performs the handoff atomically with stock exit and custody transfer. Manual handed_off returns HTTP 409 pnd_picking_handed_off_by_driver_pickup.

Frontend integration contract

Keep lifecycle-managed picking orders at completed while they wait for the driver. Trigger the delivery Pickup action; do not call this endpoint with handed_off. Display the localized 409 message if a stale client attempts it.

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the picking order to retrieve (required) UUID of the picking order to update UUID of the picking order to retrieve (required) UUID of the picking order to update

Query parameters

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

Headers

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

Body parameters

Parameter	Type	Description
status	string	—
assigned_to	string	—
item_details	array<object>	—
item_details.item_id	string	—
item_details.bin_id	string	—
item_details.quantity	number	—
item_details.picked_quantity	number	—
item_details.status	string	—
picking_progress	object	—
picking_progress.total_items	number	—
picking_progress.picked_items	number	—
picking_progress.start_time	string	—

Show 4 more body fields

Additional body parameters

Parameter	Type	Description
picking_progress.end_time	null	—
picking_progress.picker_notes	string	—
notes	string	—
due_date	string	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/warehousing/picking-orders/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "status": "in_progress",6  "assigned_to": "{{new_user_id}}",7  "item_details": [8    {9      "item_id": "{{item_id_1}}",10      "bin_id": "{{bin_id_1}}",11      "quantity": 10,12      "picked_quantity": 5,13      "status": "in_progress"14    },15    {16      "item_id": "{{item_id_2}}",17      "bin_id": "{{bin_id_2}}",18      "quantity": 5,19      "picked_quantity": 3,20      "status": "in_progress"21    }22  ],23  "picking_progress": {24    "total_items": 15,25    "picked_items": 8,26    "start_time": "2023-06-01T11:00:00Z",27    "end_time": null,28    "picker_notes": "In progress, some items located"29  },30  "notes": "Updated priority for this order",31  "due_date": "2023-06-30T10:00:00Z"32}'

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

Other request examples (1)

Request example 1

text

1{2  "status": "string", // optional (pending, in_progress, completed, cancelled, handed_off)3  "assigned_to": "uuid", // optional, user ID to assign the order to4  "item_details": [5    {6      "item_id": "uuid",7      "bin_id": "uuid",8      "quantity": number,9      "picked_quantity": number10    }11  ],12  "picking_progress": {13    "total_items": number,14    "picked_items": number,15    "start_time": "timestamp",16    "end_time": "timestamp",17    "picker_notes": "string"18  },19  "notes": "string",20  "due_date": "timestamp"21}

Response examples

200 · Success Response400 · Error - Order ID Required404 · Error - Order Not Found404 · Error - Tenant Not Found403 · Error - Insufficient Permissions409 · Error - P&D Picking Handoff Completes During Driver Pickup500 · Error - Server Error

200Success Response

Response body

json

1{2  "success": true,3  "message": "Picking order updated successfully",4  "order": {5    "id": "order-uuid",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "reference_number": "PKO-00012",9    "external_reference": "EXT-12345",10    "order_type": "individual",11    "priority": 1,12    "status": "in_progress",13    "item_details": [14      {15        "item_id": "item-uuid-1",16        "bin_id": "bin-uuid-1",17        "quantity": 10,18        "picked_quantity": 5,19        "status": "in_progress"20      },21      {22        "item_id": "item-uuid-2",23        "bin_id": "bin-uuid-2",24        "quantity": 5,25        "picked_quantity": 3,26        "status": "in_progress"27      }28    ],29    "picking_progress": {30      "total_items": 15,31      "picked_items": 8,32      "start_time": "2023-06-01T11:00:00Z",33      "end_time": null,34      "picker_notes": "In progress, some items located"35    },36    "notes": "Updated priority for this order",37    "due_date": "2023-06-30T10:00:00Z",38    "created_by": "admin-uuid",39    "created_at": "2023-06-01T10:00:00Z",40    "updated_at": "2023-06-01T10:00:00Z",41    "warehouse": {42      "id": "warehouse-uuid",43      "name": "Main Warehouse",44      "code": "WH001"45    },46    "created_by_user": {47      "id": "admin-uuid",48      "first_name": "Admin",49      "last_name": "User",50      "email": "[email protected]"51    },52    "assigned_to_user": {53      "id": "user-uuid",54      "first_name": "John",55      "last_name": "Picker",56      "email": "[email protected]"57    }58  }59}