Deliveries
This section contains 1 subgroups.
Create Delivery
/external/deliveries?tenant_id={{tenant_id}}Create a new delivery using address objects instead of address IDs. This endpoint accepts pickup and delivery addresses as coordinate objects and automatically creates address records in the database. Required Fields (Body): - pickup_address (object): must include lat, lng, full_address - delivery_address (object): must include lat, lng, full_address - delivery_service_id (string) - payer_type (string): sender|receiver - payment_method (string): wallet|cod Conditionally Required: - customer_id (string): required unless caller is a customer/no-role (auto-set from auth) Optional Fields (Body): - cod_amount (number) - notes (string) - external_reference_id (string) - scheduled_pickup_time (ISO datetime) - scheduled_delivery_time (ISO datetime) - receiver_user_id (string) - priority (number 1-4) - unit_size (number) - bulk_group (string) - tracking_provider (string) - bulk_operation_id (string) - package_details (object) Responses: 201 created, 400 validation failure, 404 delivery_service_not_found, 500 internal_server_error.
1curl --request POST "$ONDI_BASE_URL/external/deliveries?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}" \4 --header "Content-Type: application/json" \5 --header "Content-Type: application/json" \6 --data '{7 "pickup_address": {8 "lat": {{pickup_lat}},9 "lng": {{pickup_lng}},10 "full_address": "{{pickup_full_address}}",11 "city": "{{pickup_city}}",12 "state": "{{pickup_state}}",13 "country": "{{pickup_country}}",14 "postal_code": "{{pickup_postal_code}}"15 },16 "delivery_address": {17 "lat": {{delivery_lat}},18 "lng": {{delivery_lng}},19 "full_address": "{{delivery_full_address}}",20 "city": "{{delivery_city}}",21 "state": "{{delivery_state}}",22 "country": "{{delivery_country}}",23 "postal_code": "{{delivery_postal_code}}"24 },25 "customer_id": "{{customer_id}}",26 "delivery_service_id": "{{delivery_service_id}}",27 "payer_type": "sender",28 "payment_method": "wallet",29 "cod_amount": 0,30 "notes": "Package delivery",31 "external_reference_id": "EXT-REF-123",32 "scheduled_pickup_time": "2024-01-15T10:00:00Z",33 "scheduled_delivery_time": "2024-01-15T14:00:00Z",34 "receiver_user_id": "{{receiver_user_id}}",35 "priority": 1,36 "unit_size": 1,37 "bulk_group": "GROUP-001",38 "tracking_provider": "internal",39 "bulk_operation_id": "BULK-OP-123",40 "package_details": {41 "special_instructions": "Handle with care",42 "items": [43 {44 "name": "{{item_name}}",45 "description": "{{item_description}}",46 "quantity": 1,47 "weight": 2.5,48 "length": 30,49 "width": 20,50 "height": 1551 }52 ]53 }54}'1{2 "pickup_address": {3 "lat": {{pickup_lat}},4 "lng": {{pickup_lng}},5 "full_address": "{{pickup_full_address}}",6 "city": "{{pickup_city}}",7 "state": "{{pickup_state}}",8 "country": "{{pickup_country}}",9 "postal_code": "{{pickup_postal_code}}"10 },11 "delivery_address": {12 "lat": {{delivery_lat}},13 "lng": {{delivery_lng}},14 "full_address": "{{delivery_full_address}}",15 "city": "{{delivery_city}}",16 "state": "{{delivery_state}}",17 "country": "{{delivery_country}}",18 "postal_code": "{{delivery_postal_code}}"19 },20 "customer_id": "{{customer_id}}",21 "delivery_service_id": "{{delivery_service_id}}",22 "payer_type": "sender",23 "payment_method": "wallet",24 "cod_amount": 0,25 "notes": "Package delivery",26 "external_reference_id": "EXT-REF-123",27 "scheduled_pickup_time": "2024-01-15T10:00:00Z",28 "scheduled_delivery_time": "2024-01-15T14:00:00Z",29 "receiver_user_id": "{{receiver_user_id}}",30 "priority": 1,31 "unit_size": 1,32 "bulk_group": "GROUP-001",33 "tracking_provider": "internal",34 "bulk_operation_id": "BULK-OP-123",35 "package_details": {36 "special_instructions": "Handle with care",37 "items": [38 {39 "name": "{{item_name}}",40 "description": "{{item_description}}",41 "quantity": 1,42 "weight": 2.5,43 "length": 30,44 "width": 20,45 "height": 1546 }47 ]48 }49}Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "delivery_created_successfully",4 "delivery": {5 "id": "DEL-000001",6 "status": "pending",7 "delivery_fee": 15.5,8 "external_reference_id": "EXT-REF-123",9 "priority": 1,10 "delivery_type": "standard",11 "unit_size": 1,12 "cod_amount": 0,13 "created_at": "2024-01-15T08:00:00Z"14 },15 "pickup_address": {16 "id": "address-uuid-1",17 "full_address": "123 Main St, New York, NY 10001",18 "latitude": 40.7128,19 "longitude": -74.00620 },21 "delivery_address": {22 "id": "address-uuid-2",23 "full_address": "456 Broadway, New York, NY 10013",24 "latitude": 40.7589,25 "longitude": -73.985126 }27}1{2 "success": false,3 "message": "pickup_address_lat_lng_must_be_numbers"4}1{2 "success": false,3 "message": "delivery_address_required"4}List Deliveries
/external/deliveries?tenant_id={{tenant_id}}&page=1&limit=10Retrieve a list of deliveries with optional filtering and pagination. Required (query): tenant_id Optional (query): page, limit, status, customer_id, search, driver_id, zone_ids, bulk_group, delivery_type, payer_type, is_completed, payment_method, payment_status, delivery_service_id, start_date, end_date, assignment_status. Responses: 200 success.
1curl --request GET "$ONDI_BASE_URL/external/deliveries?tenant_id={{tenant_id}}&page=1&limit=10" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}"Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
pageOptional1
Page number for pagination (Optional, default: 1)
limitOptional10
Number of deliveries per page (Optional, default: 10)
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Responses
1{2 "success": true,3 "message": "deliveries_retrieved_successfully",4 "deliveries": [5 {6 "id": "delivery-uuid-1",7 "status": "pending",8 "delivery_fee": 15.5,9 "customer": {10 "id": "customer-123",11 "name": "John Doe"12 },13 "pickup_location": {14 "full_address": "123 Main St, New York, NY 10001"15 },16 "delivery_location": {17 "full_address": "456 Broadway, New York, NY 10013"18 }19 }20 ],21 "page": 1,22 "limit": 10,23 "total": 2524}Get Delivery
/external/deliveries/{{delivery_id}}?tenant_id={{tenant_id}}Retrieve details of a specific delivery by its ID, delivery code, or barcode. Required (query): tenant_id Optional (query): filter_type (defaults to 'id') Responses: 200 success, 404 delivery_not_found.
1curl --request GET "$ONDI_BASE_URL/external/deliveries/{{delivery_id}}?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}"Path parameters
delivery_idRequiredVariable used inside the request path.
Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Responses
1{2 "success": true,3 "message": "delivery_retrieved_successfully",4 "delivery": {5 "id": "delivery-uuid-123",6 "status": "pending",7 "delivery_fee": 15.5,8 "customer": {9 "id": "customer-123",10 "name": "John Doe",11 "email": "john@example.com"12 },13 "pickup_location": {14 "id": "address-uuid-1",15 "full_address": "123 Main St, New York, NY 10001",16 "latitude": 40.7128,17 "longitude": -74.00618 },19 "delivery_location": {20 "id": "address-uuid-2",21 "full_address": "456 Broadway, New York, NY 10013",22 "latitude": 40.7589,23 "longitude": -73.985124 },25 "created_at": "2024-01-15T08:00:00Z",26 "scheduled_pickup_time": "2024-01-15T10:00:00Z",27 "scheduled_delivery_time": "2024-01-15T14:00:00Z"28 }29}1{2 "success": false,3 "message": "delivery_not_found"4}Update Delivery
/external/deliveries/{{delivery_id}}?tenant_id={{tenant_id}}Update an existing delivery. You can update address objects, notes, scheduled times, and other delivery details. Updatable Fields (Body): - pickup_address (object): New pickup location (creates new address) - delivery_address (object): New delivery location (creates new address) - customer_id (string) - delivery_service_id (string) - payer_type (string) - payment_method (string) - cod_amount (number) - notes (string) - external_reference_id (string) - scheduled_pickup_time (ISO datetime) - scheduled_delivery_time (ISO datetime) - receiver_user_id (string) - priority (number) - unit_size (number) - bulk_group (string) - tracking_provider (string) - bulk_operation_id (string) - package_details (object) Required (query): tenant_id Responses: 200 success, 400 validation failure, 404 delivery_update_failed.
1curl --request PUT "$ONDI_BASE_URL/external/deliveries/{{delivery_id}}?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}" \4 --header "Content-Type: application/json" \5 --header "Content-Type: application/json" \6 --data '{7 "pickup_address": {8 "lat": {{new_pickup_lat}},9 "lng": {{new_pickup_lng}},10 "full_address": "{{new_pickup_full_address}}",11 "city": "{{new_pickup_city}}",12 "state": "{{new_pickup_state}}",13 "country": "{{new_pickup_country}}",14 "postal_code": "{{new_pickup_postal_code}}"15 },16 "delivery_address": {17 "lat": {{new_delivery_lat}},18 "lng": {{new_delivery_lng}},19 "full_address": "{{new_delivery_full_address}}",20 "city": "{{new_delivery_city}}",21 "state": "{{new_delivery_state}}",22 "country": "{{new_delivery_country}}",23 "postal_code": "{{new_delivery_postal_code}}"24 },25 "customer_id": "{{new_customer_id}}",26 "delivery_service_id": "{{new_delivery_service_id}}",27 "payer_type": "receiver",28 "payment_method": "cod",29 "cod_amount": 25.00,30 "notes": "Updated delivery notes - handle with care",31 "external_reference_id": "EXT-REF-UPDATED-456",32 "scheduled_pickup_time": "2024-01-15T11:00:00Z",33 "scheduled_delivery_time": "2024-01-15T15:00:00Z",34 "receiver_user_id": "{{new_receiver_user_id}}",35 "priority": 2,36 "delivery_type": "express",37 "unit_size": 2,38 "bulk_group": "GROUP-002",39 "tracking_provider": "fedex",40 "bulk_operation_id": "BULK-OP-456",41 "package_details": {42 "special_instructions": "Handle with care",43 "items": [44 {45 "name": "{{item_name}}",46 "description": "{{item_description}}",47 "quantity": 1,48 "weight": 3.5,49 "length": 35,50 "width": 25,51 "height": 2052 }53 ]54 }55}'1{2 "pickup_address": {3 "lat": {{new_pickup_lat}},4 "lng": {{new_pickup_lng}},5 "full_address": "{{new_pickup_full_address}}",6 "city": "{{new_pickup_city}}",7 "state": "{{new_pickup_state}}",8 "country": "{{new_pickup_country}}",9 "postal_code": "{{new_pickup_postal_code}}"10 },11 "delivery_address": {12 "lat": {{new_delivery_lat}},13 "lng": {{new_delivery_lng}},14 "full_address": "{{new_delivery_full_address}}",15 "city": "{{new_delivery_city}}",16 "state": "{{new_delivery_state}}",17 "country": "{{new_delivery_country}}",18 "postal_code": "{{new_delivery_postal_code}}"19 },20 "customer_id": "{{new_customer_id}}",21 "delivery_service_id": "{{new_delivery_service_id}}",22 "payer_type": "receiver",23 "payment_method": "cod",24 "cod_amount": 25.00,25 "notes": "Updated delivery notes - handle with care",26 "external_reference_id": "EXT-REF-UPDATED-456",27 "scheduled_pickup_time": "2024-01-15T11:00:00Z",28 "scheduled_delivery_time": "2024-01-15T15:00:00Z",29 "receiver_user_id": "{{new_receiver_user_id}}",30 "priority": 2,31 "delivery_type": "express",32 "unit_size": 2,33 "bulk_group": "GROUP-002",34 "tracking_provider": "fedex",35 "bulk_operation_id": "BULK-OP-456",36 "package_details": {37 "special_instructions": "Handle with care",38 "items": [39 {40 "name": "{{item_name}}",41 "description": "{{item_description}}",42 "quantity": 1,43 "weight": 3.5,44 "length": 35,45 "width": 25,46 "height": 2047 }48 ]49 }50}Path parameters
delivery_idRequiredVariable used inside the request path.
Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "delivery_updated_successfully",4 "delivery": {5 "id": "delivery-uuid-123",6 "status": "pending",7 "notes": "Updated delivery notes",8 "scheduled_pickup_time": "2024-01-15T11:00:00Z",9 "updated_at": "2024-01-15T09:30:00Z"10 }11}1{2 "success": false,3 "message": "delivery_update_failed"4}Update Delivery Status By Code
/external/deliveries/code/{{delivery_code}}/status?tenant_id={{tenant_id}}Update a delivery status using delivery_code instead of delivery ID. The authenticated external caller can update only deliveries they own. Required (query): tenant_id Required (body): target_delivery_status Conditionally required (body): driver_id only when the target status needs an assignment, the delivery has no active assignment, and tenant settings do not define assignment_change_settings.default_driver_id. Optional (body): reason, notes, proof_of_delivery.signature_url, proof_of_delivery.photo_urls. Supported target statuses: - pending - assigned - picked_up - in_transit - delivered - cancelled - returned Behavior: - Uses the same delivery status workflow as the internal panel endpoint. - When an assignment is needed, the backend uses request driver_id first, then falls back to assignment_change_settings.default_driver_id. - delivered allows optional proof of delivery. - Lookup is by delivery_code, but status changes are applied only when the delivery belongs to the authenticated external caller. Responses: 200 success, 400 validation failure, 404 delivery_not_found, 409 invalid transition/business conflict.
1curl --request POST "$ONDI_BASE_URL/external/deliveries/code/{{delivery_code}}/status?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}" \4 --header "Content-Type: application/json" \5 --header "Content-Type: application/json" \6 --data '{7 "target_delivery_status": "delivered",8 "driver_id": "{{driver_id}}",9 "notes": "Delivered by external integration",10 "proof_of_delivery": {11 "signature_url": "{{signature_url}}",12 "photo_urls": [13 "{{proof_photo_url_1}}"14 ]15 }16}'1{2 "target_delivery_status": "delivered",3 "driver_id": "{{driver_id}}",4 "notes": "Delivered by external integration",5 "proof_of_delivery": {6 "signature_url": "{{signature_url}}",7 "photo_urls": [8 "{{proof_photo_url_1}}"9 ]10 }11}Path parameters
delivery_codeRequiredVariable used inside the request path.
Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
Request body fields
target_delivery_statusExampleExample field from the request body.
driver_idExampleExample field from the request body.
notesExampleExample field from the request body.
proof_of_deliveryExampleExample field from the request body.
proof_of_delivery.signature_urlExampleExample field from the request body.
proof_of_delivery.photo_urlsExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Content-TypeOptionalapplication/json
Responses
1{2 "success": true,3 "message": "delivery_status_updated_successfully",4 "delivery": {5 "id": "delivery-uuid-123",6 "delivery_code": 100245,7 "status": "delivered"8 }9}1{2 "success": false,3 "message": "driver_id_required_for_delivery_status"4}1{2 "success": false,3 "message": "delivery_not_found"4}Delete Delivery
/external/deliveries/{{delivery_id}}?tenant_id={{tenant_id}}Delete (cancel) a delivery. This performs a soft delete by setting the delivery status to 'cancelled'. Required (query): tenant_id Responses: 200 success, 400 cannot_delete_delivery_in_progress, 404 delivery_not_found.
1curl --request DELETE "$ONDI_BASE_URL/external/deliveries/{{delivery_id}}?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}"Path parameters
delivery_idRequiredVariable used inside the request path.
Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Responses
1{2 "success": true,3 "message": "delivery_deleted_successfully"4}1{2 "success": false,3 "message": "cannot_delete_delivery_in_progress"4}Cancel Delivery
/external/deliveries/{{delivery_id}}/cancel?tenant_id={{tenant_id}}Cancel a delivery by setting its status to 'cancelled'. Allowed for tenant admins or the owning customer. Not allowed if status is delivered, failed, cancelled, or rejected. Required (query): tenant_id Responses: 200 success, 400 cannot_cancel_*, 403 unauthorized, 404 delivery_not_found.
1curl --request POST "$ONDI_BASE_URL/external/deliveries/{{delivery_id}}/cancel?tenant_id={{tenant_id}}" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "X-API-Key: {{api_key}}"Path parameters
delivery_idRequiredVariable used inside the request path.
Query parameters
tenant_idOptional{{tenant_id}}
ID of the tenant (Required)
Headers
AuthorizationOptionalBearer {{access_token}}
X-API-KeyOptional{{api_key}}
Responses
1{2 "success": true,3 "message": "delivery_cancelled_successfully",4 "delivery": {5 "id": "delivery-uuid-123",6 "status": "cancelled"7 }8}1{2 "success": false,3 "message": "cannot_cancel_delivery_after_delivery"4}1{2 "success": false,3 "message": "unauthorized"4}1{2 "success": false,3 "message": "delivery_not_found"4}