Package Handoffs Management

4 API calls in this section.

Endpoints for managing package handoffs between warehouse staff and delivery drivers. These APIs provide functionality for creating, retrieving, listing, and updating handoff records with their status, signature URLs, and related entities.

List Package Handoffs

Warehousing / Package Handoffs Management

GET/warehousing/handoffs

Retrieves package handoffs based on specified filter criteria. Supports pagination and filtering by warehouse, delivery ID, driver ID, warehouse staff ID, and status.

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

Response

• Returns a paginated list of package handoffs

• Includes related entities such as warehouse, picking order, and warehouse staff information

• Includes a status_matrix summary for the current non-status filters

• 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 ID (optional) Filter by warehouse ID (optional)
delivery_idOptional	string	Filter by delivery ID (optional) Filter by delivery ID (optional)
driver_idOptional	string	Filter by driver ID (optional) Filter by driver ID (optional)
warehouse_staff_idOptional	string	Filter by warehouse staff ID (optional) Filter by warehouse staff ID (optional)
statusOptional	string	Filter by handoff status: pending, in_progress, completed (optional) Filter by handoff status (pending, in_progress, completed) Filter by handoff status: pending, in_progress, completed (optional) Filter by handoff status (pending, in_progress, completed)
searchOptional	string	Search term to filter by status (optional) Search term to filter by status (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: 10) Number of items per page (default: 10) Number of items per page (optional, default: 10) Number of items per page (default: 10) Example: 10

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/handoffs?tenant_id=${TENANT_ID}&warehouse_id=&delivery_id=&driver_id=&warehouse_staff_id=&status=&search=&page=1&limit=10" \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": "Handoffs retrieved successfully",4  "handoffs": [5    {6      "id": "12345678-1234-1234-1234-123456789012",7      "tenant_id": "tenant-uuid",8      "warehouse_id": "warehouse-uuid",9      "delivery_id": "delivery-uuid",10      "picking_order_id": "picking-order-uuid",11      "warehouse_staff_id": "staff-uuid",12      "driver_id": "driver-uuid",13      "status": "completed",14      "signature_url": "https://example.com/signatures/sig123.png",15      "notes": "Handoff completed without issues",16      "initiated_at": "2023-05-15T14:30:00Z",17      "completed_at": "2023-05-15T14:45:00Z",18      "warehouse": {19        "id": "warehouse-uuid",20        "name": "Main Warehouse",21        "code": "WH001"22      },23      "picking_order": {24        "id": "picking-order-uuid",25        "reference_number": "PO-12345"26      },27      "warehouse_staff": {28        "id": "staff-uuid",29        "user_id": {30          "id": "user-uuid",31          "full_name": "John Smith"32        }33      }34    }35  ],36  "status_matrix": {37    "pending": 4,38    "in_progress": 2,39    "completed": 8,40    "total": 1441  },42  "page": 1,43  "limit": 10,44  "total": 145}

Create Package Handoff

Warehousing / Package Handoffs Management

POST/warehousing/handoffs

Assignment owns prepared P&D handoff creation. If an eligible P&D assignment already created the pending handoff, matching warehouse and picking-order input returns that same handoff with HTTP 200 and may fill its previously empty warehouse staff. This idempotent result also applies while driver acceptance is pending. Non-P&D legacy creation keeps its existing rules and returns HTTP 201 for a new record.

Records or returns a package handoff from warehouse staff to a delivery driver.

• User must have manage:operations:tenant permission

Business Rules

• warehouse_id, delivery_id, picking_order_id, and warehouse_staff_id are required and tenant-scoped.

• The picking order must be completed.

• For prepared P&D/operational-return work, assignment is the handoff owner. A matching request returns the existing pending handoff with HTTP 200, including when the assignment is still pending; warehouse, picking order, assignment, and driver must match current preparation.

• For non-P&D legacy creation, the delivery assignment must be assigned, accepted, or en_route_to_pickup, no active handoff may already exist, and a new pending record returns HTTP 201.

• driver_id is resolved from the current active assignment.

• Pickup or later states are outside the creation window.

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	—
delivery_id	string	—
picking_order_id	string	—
warehouse_staff_id	string	—
driver_id	string	—
signature_url	string	—
notes	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/warehousing/handoffs?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "warehouse_id": "warehouse-uuid",6  "delivery_id": "delivery-uuid",7  "picking_order_id": "picking-order-uuid",8  "warehouse_staff_id": "staff-uuid",9  "driver_id": "driver-uuid",10  "signature_url": "https://example.com/signatures/sig123.png",11  "notes": "Package ready for handoff"12}'

Other request examples (1)

Request example 1

json

1{2  "warehouse_id": "uuid",3  "delivery_id": "uuid",4  "picking_order_id": "uuid",5  "warehouse_staff_id": "uuid",6  "driver_id": "uuid",7  "signature_url": "string",8  "notes": "string"9}

Response examples

200 · Success - Existing P&D Handoff201 · Success Response400 · Error - Missing Required Field404 · Error - Warehouse Not Found404 · Error - Delivery Not Found404 · Error - Picking Order Not Found400 · Error - Picking Order Not Completed400 · Error - Handoff Already Exists403 · Error - Insufficient Permissions400 · Error - Invalid Request Body

200OK

Response body

json

1{2  "success": true,3  "message": "Handoff created successfully",4  "handoff": {5    "id": "existing-handoff-uuid",6    "delivery_id": "delivery-uuid",7    "picking_order_id": "picking-order-uuid",8    "assignment_id": "assignment-uuid",9    "driver_id": "driver-uuid",10    "warehouse_staff_id": "staff-uuid",11    "status": "pending"12  }13}

Get Package Handoff

Warehousing / Package Handoffs Management

GET/warehousing/handoffs/:id

Retrieves detailed information about a specific package handoff including related entities such as warehouse, picking order, warehouse staff, driver, and delivery information.

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

Response

• Returns detailed information about the specified handoff

• Includes related entities information (warehouse, picking order, staff, driver)

• Includes delivery details such as delivery code, pickup/drop-off locations, and customer information

Path parameters

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

Response examples

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

200Success Response

Response body

json

1{2  "success": true,3  "message": "Handoff retrieved successfully",4  "handoff": {5    "id": "12345678-1234-1234-1234-123456789012",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "delivery_id": "delivery-uuid",9    "picking_order_id": "picking-order-uuid",10    "warehouse_staff_id": "staff-uuid",11    "driver_id": "driver-uuid",12    "status": "completed",13    "signature_url": "https://example.com/signatures/sig123.png",14    "notes": "Handoff completed without issues",15    "initiated_at": "2023-05-15T14:30:00Z",16    "completed_at": "2023-05-15T14:45:00Z",17    "warehouse": {18      "id": "warehouse-uuid",19      "name": "Main Warehouse",20      "code": "WH001"21    },22    "picking_order": {23      "id": "picking-order-uuid",24      "reference_number": "PO-12345"25    },26    "warehouse_staff": {27      "id": "staff-uuid",28      "user_id": {29        "id": "user-uuid",30        "full_name": "John Smith"31      }32    },33    "driver": {34      "id": "driver-uuid",35      "user_id": {36        "id": "user-uuid",37        "full_name": "Jane Doe"38      }39    },40    "delivery": {41      "id": "delivery-uuid",42      "delivery_code": "DLV-000123",43      "status": "assigned",44      "pickup": {45        "id": "pickup-location-uuid",46        "full_address": "123 Warehouse Street, City, State 12345"47      },48      "drop_off": {49        "id": "dropoff-location-uuid",50        "full_address": "456 Customer Avenue, City, State 67890"51      },52      "customer": {53        "id": "customer-uuid",54        "full_name": "John Customer"55      }56    }57  }58}

Update Package Handoff

Warehousing / Package Handoffs Management

PUT/warehousing/handoffs/:id

Updates an existing package handoff with new information such as status, driver assignment, signature, or notes. Special validation rules apply when marking handoffs as completed.

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

Business Rules

• At least one field must be provided for update

• Valid status values are: pending, in_progress, completed

• If driver_id is provided, the driver must exist and belong to the tenant

• A lifecycle-managed P&D/operational-return handoff has assignment_id. Do not send status=completed for it; the assigned driver's Pickup action completes the handoff atomically with stock and custody. Manual completion returns HTTP 409 pnd_handoff_completed_by_driver_pickup.

• Special rules for legacy 'completed' status:

  • delivery_id must be present in the handoff record

  • The delivery must have a driver assignment in a pre-pickup state: assigned, accepted, or en_route_to_pickup

  • If the delivery is already picked_up or beyond, the handoff can no longer be completed through this warehouse step

  • signature_url is mandatory for completion

  • driver_id will be automatically set from the delivery assignment

• If status is changed to 'completed', the completed_at timestamp is set automatically

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the package handoff to update (required) UUID of the package handoff to update (required) Example: handoff-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 context) UUID of the tenant (required if not in auth) UUID of the tenant (required if not in auth context) 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	—
driver_id	string	—
signature_url	string	—
notes	string	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/warehousing/handoffs/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "status": "completed",6  "driver_id": "driver-uuid",7  "signature_url": "https://example.com/signatures/sig123.png",8  "notes": "Updated notes for the handoff"9}'

Other request examples (1)

Request example 1

text

1{2  "status": "string", // optional (pending, in_progress, completed)3  "driver_id": "uuid", // optional - auto-set when status becomes completed4  "signature_url": "string", // optional - required for completed status5  "notes": "string" // optional6}

Response examples

200 · Success Response404 · Error - Handoff Not Found404 · Error - Driver Not Found400 · Error - Invalid Status400 · Error - No Fields to Update404 · Error - Tenant Not Found403 · Error - Insufficient Permissions400 · Error - Delivery ID Required for Completion400 · Error - Delivery Not Assigned to Driver400 · Error - Signature URL Required for Completion409 · Error - P&D Handoff Completes During Driver Pickup400 · Error - Invalid Request Body

200Success Response

Response body

json

1{2  "success": true,3  "message": "Handoff updated successfully",4  "handoff": {5    "id": "12345678-1234-1234-1234-123456789012",6    "tenant_id": "tenant-uuid",7    "warehouse_id": "warehouse-uuid",8    "delivery_id": "delivery-uuid",9    "picking_order_id": "picking-order-uuid",10    "warehouse_staff_id": "staff-uuid",11    "driver_id": "driver-uuid",12    "status": "completed",13    "signature_url": "https://example.com/signatures/sig123.png",14    "notes": "Updated notes for the handoff",15    "initiated_at": "2023-05-15T14:30:00Z",16    "completed_at": "2023-05-15T15:30:00Z"17  }18}