Return Requests

6 API calls in this section.

Delivery Return Requests API (single-flow).

Create Return Request (Customer)

Delivery & Last-Mile / Return Requests

POST/delivery/returns

Create a return request for a delivered delivery.

Flow

• Creates a return_requests record with status = pending

• Updates the original delivery return_status = return_requested

• If system_settings(scope=tenant).return_requests.auto_approval = true, the system auto-approves and creates a return delivery using default_delivery_service_id and destination_mode. The configured service must be active and have allow_returns=true.

Return Delivery Payment Settings

• Return deliveries are ALWAYS created with payment_method = wallet and payer_type = sender (customer pays via wallet), regardless of the original delivery's payment settings.

Endpoint alias

• Same payload is also accepted at POST /delivery/returns/request.

Business Rules

• Delivery must have status = delivered

• Only one non-cancelled return request per delivery

• An open delivery exception or Waybill missing_on_receive discrepancy returns HTTP 409 delivery_has_open_exception; a missing receipt must be resolved as found or lost before a return request can be created

Query parameters

Parameter	Type	Description
tenant_idRequired	string	UUID of the tenant (required) UUID of the tenant (required) Example: {{tenant_id}}
languageOptional	string	Preferred language (optional) Preferred language (optional) Example: en

Headers

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

Body parameters

Parameter	Type	Description
delivery_id	string	—
return_reason	string	—
notes	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/delivery/returns?tenant_id=${TENANT_ID}&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \4  --header "Content-Type: application/json" \5  --data-raw '{6  "delivery_id": "delivery-uuid",7  "return_reason": "Damaged product",8  "notes": "Package arrived with visible damage"9}'

Response examples

201 · Success - Pending (auto_approval=false)201 · Success - Auto Approved (auto_approval=true)400 · Error - Delivery Not Eligible400 · Error - Return Already Exists

201Success - Pending (auto_approval=false)

Response body

json

1{2  "success": true,3  "message": "return_request_created",4  "return_request_id": "return-request-uuid",5  "auto_approved": false6}

Create Return Request (Customer) - Alias

Delivery & Last-Mile / Return Requests

POST/delivery/returns/request

Alias of POST /delivery/returns (kept for compatibility). Same behavior and payload.

Query parameters

Parameter	Type	Description
tenant_idRequired	string	UUID of the tenant (required) UUID of the tenant (required) Example: {{tenant_id}}
languageOptional	string	Preferred language (optional) Preferred language (optional) Example: en

Headers

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

Body parameters

Parameter	Type	Description
delivery_id	string	—
return_reason	string	—
notes	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/delivery/returns/request?tenant_id=${TENANT_ID}&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \4  --header "Content-Type: application/json" \5  --data-raw '{6  "delivery_id": "delivery-uuid",7  "return_reason": "Damaged product",8  "notes": "Package arrived with visible damage"9}'

Response examples

No saved response example. Use Try it to inspect a staging response.

List Return Requests (Admin)

Delivery & Last-Mile / Return Requests

GET/delivery/returns/requests

List return requests for a tenant with pagination, sorting, column filters and stats.

Query parameters

Parameter	Type	Description
page	string	Page number (default: 1) Page number (default: 1) Example: 1
limit	string	Items per page (default: 10) Items per page (default: 10) Example: 10
status	string	Filter by return request status: pending, approved, cancelled Filter by return request status: pending, approved, cancelled
search	string	Search across original_delivery_code, return_delivery_code, customer_name (ILIKE) Search across original_delivery_code, return_delivery_code, customer_name (ILIKE)
sort_by	string	Sort column: delivery_code | return_delivery_code | customer_name | requested_at (default: requested_at) Sort column: delivery_code | return_delivery_code | customer_name | requested_at (default: requested_at)
sort_order	string	asc or desc (default: desc) asc or desc (default: desc) Example: desc
column_filters	string	JSON object. Keys: delivery_code (string ILIKE), return_delivery_code (string ILIKE), customer_name (string ILIKE), return_reason (string ILIKE), status (string exact), requested_at ({from?, to?} date range). Example: {"status":"pending","requested_at":{"from":"2025-01-01","to":"2025-01-31"}} JSON object. Keys: delivery_code (string ILIKE), return_delivery_code (string ILIKE), customer_name (string ILIKE), return_reason (string ILIKE), status (string exact), requested_at ({from?, to?} date range). Example: {"status":"pending","requested_at":{"from":"2025-01-01","to":"2025-01-31"}}
tenant_idOptional	string	Tenant ID (optional if in auth token) Tenant ID (optional if in auth token)
language	string	Preferred language Preferred language Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/delivery/returns/requests?page=1&limit=10&status=&search=&sort_by=&sort_order=desc&column_filters=&tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success400 · Error - Invalid column_filters JSON

200OK

Response body

json

1{2  "success": true,3  "message": "return_requests_retrieved",4  "data": {5    "returns": [6      {7        "id": "uuid",8        "delivery_id": "uuid",9        "return_delivery_id": null,10        "return_reason": "Damaged product",11        "status": "pending",12        "requested_at": "2025-01-15T10:00:00Z",13        "notes": null,14        "original_delivery_code": 1001,15        "return_delivery_code": null,16        "original_delivery_status": "delivered",17        "return_delivery_status": null,18        "customer_name": "John Doe"19      }20    ],21    "total": 42,22    "stats": {23      "totalReturns": 100,24      "pendingReturns": 15,25      "approvedReturns": 75,26      "recentlyAddedCount": 827    }28  }29}

Get Return Request (Admin)

Delivery & Last-Mile / Return Requests

GET/delivery/returns/requests/:id

Get return request details including original delivery + (optional) warehouse + (optional) created return delivery.

Path parameters

Parameter	Type	Description
idRequired	string	Example: return-request-uuid

Query parameters

Parameter	Type	Description
tenant_idRequired	string	UUID of the tenant (required) UUID of the tenant (required) Example: {{tenant_id}}
languageOptional	string	Preferred language (optional) Preferred language (optional) Example: en

Headers

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

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/delivery/returns/requests/${ID}?tenant_id=${TENANT_ID}&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \4  --header "Content-Type: application/json"

Response examples

No saved response example. Use Try it to inspect a staging response.

Delete Return Request (Admin)

Delivery & Last-Mile / Return Requests

DELETE/delivery/returns/:id

Delete a return request by ID.

Path parameters

Parameter	Type	Description
idRequired	string	Example: return-request-uuid

Query parameters

Parameter	Type	Description
tenant_idOptional	string	Tenant ID (optional if in auth token) Tenant ID (optional if in auth token)
language	string	Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/delivery/returns/${ID}?tenant_id=&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success404 · Error - Not Found

200OK

Response body

json

1{2  "success": true,3  "data": {4    "id": "return-request-uuid"5  }6}

Approve Return Request (Admin)

Delivery & Last-Mile / Return Requests

POST/delivery/returns/:id/approve

Approve a pending return request and create the return delivery using tenant setting return_requests (default service + destination mode). The configured default service must be active and have allow_returns=true.

Payment Settings

• Return delivery is created with payment_method = wallet and payer_type = sender (customer pays via wallet).

Pickup Address Resolution

• Uses original.delivery_location_id if present, otherwise falls back to original.delivery_location JSON (the original dropoff address).

• Returns original_delivery_dropoff_address_missing only when both are absent.

Note

this endpoint has no request body; it is fully driven by settings.

Path parameters

Parameter	Type	Description
idRequired	string	Example: return-request-uuid

Query parameters

Parameter	Type	Description
tenant_idRequired	string	UUID of the tenant (required) UUID of the tenant (required) Example: {{tenant_id}}
languageOptional	string	Preferred language (optional) Preferred language (optional) Example: en

Headers

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

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/delivery/returns/${ID}/approve?tenant_id=${TENANT_ID}&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \4  --header "Content-Type: application/json"

Response examples

200 · Success400 · Dropoff Address Missing

200Success

Response body

json

1{2  "success": true,3  "message": "return_request_approved",4  "return_delivery_id": "return-delivery-uuid"5}