Return Requests

6 API calls in this section.

Create Return Request (Customer)

Delivery & Last-Mile / Return Requests

POST/delivery/returns?tenant_id={{tenant_id}}&language=en

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

Send a bearer token in Authorization and a tenant API key when the integration requires X-APIKey or X-API-Key.

Request

curl

1curl --request POST "$ONDI_BASE_URL/delivery/returns?tenant_id={{tenant_id}}&language=en" \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  "delivery_id": "delivery-uuid",8  "return_reason": "Damaged product",9  "notes": "Package arrived with visible damage"10}'

Request body

json

1{2  "delivery_id": "delivery-uuid",3  "return_reason": "Damaged product",4  "notes": "Package arrived with visible damage"5}

Query parameters

tenant_idOptional

query string

{{tenant_id}}

UUID of the tenant (required)

languageOptional

query string

en

Preferred language (optional)

Request body fields

delivery_idExample

string

Example field from the request body.

return_reasonExample

string

Example field from the request body.

notesExample

string

Example field from the request body.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

X-API-KeyOptional

header string

{{api_key}}

Content-TypeOptional

header string

application/json

Responses

Success - Pending (auto_approval=false)201

Response body

json

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

Success - Auto Approved (auto_approval=true)201

Response body

json

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

Error - Delivery Not Eligible400

Response body

json

1{2  "success": false,3  "message": "delivery_not_eligible_for_return"4}

Error - Return Already Exists400

Response body

json

1{2  "success": false,3  "message": "return_already_exists_for_delivery"4}

Create Return Request (Customer) - Alias

Delivery & Last-Mile / Return Requests

POST/delivery/returns/request?tenant_id={{tenant_id}}&language=en

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

Send a bearer token in Authorization and a tenant API key when the integration requires X-APIKey or X-API-Key.

Request

curl

1curl --request POST "$ONDI_BASE_URL/delivery/returns/request?tenant_id={{tenant_id}}&language=en" \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  "delivery_id": "delivery-uuid",8  "return_reason": "Damaged product",9  "notes": "Package arrived with visible damage"10}'

Request body

json

1{2  "delivery_id": "delivery-uuid",3  "return_reason": "Damaged product",4  "notes": "Package arrived with visible damage"5}

Query parameters

tenant_idOptional

query string

{{tenant_id}}

UUID of the tenant (required)

languageOptional

query string

en

Preferred language (optional)

Request body fields

delivery_idExample

string

Example field from the request body.

return_reasonExample

string

Example field from the request body.

notesExample

string

Example field from the request body.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

X-API-KeyOptional

header string

{{api_key}}

Content-TypeOptional

header string

application/json

Responses

No response example is available for this endpoint yet.

List Return Requests (Admin)

Delivery & Last-Mile / Return Requests

GET/delivery/returns/requests?page=1&limit=10&status=&search=&sort_by=&sort_order=desc&column_filters=&tenant_id=&language=en

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

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/delivery/returns/requests?page=1&limit=10&status=&search=&sort_by=&sort_order=desc&column_filters=&tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Query parameters

pageOptional

query string

1

Page number (default: 1)

limitOptional

query string

10

Items per page (default: 10)

statusOptional

query string

Filter by return request status: pending, approved, cancelled

searchOptional

query string

Search across original_delivery_code, return_delivery_code, customer_name (ILIKE)

sort_byOptional

query string

Sort column: delivery_code | return_delivery_code | customer_name | requested_at (default: requested_at)

sort_orderOptional

query string

desc

asc or desc (default: desc)

column_filtersOptional

query 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"}}

tenant_idOptional

query string

Tenant ID (optional if in auth token)

languageOptional

query string

en

Preferred language

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Responses

Success200OK

Error - Invalid column_filters JSON400Bad Request

Get Return Request (Admin)

Delivery & Last-Mile / Return Requests

GET/delivery/returns/requests/:id?tenant_id={{tenant_id}}&language=en

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

Send a bearer token in Authorization and a tenant API key when the integration requires X-APIKey or X-API-Key.

Request

curl

1curl --request GET "$ONDI_BASE_URL/delivery/returns/requests/:id?tenant_id={{tenant_id}}&language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "X-API-Key: {{api_key}}" \4  --header "Content-Type: application/json"

Path parameters

idRequired

path string

return-request-uuid

Query parameters

tenant_idOptional

query string

{{tenant_id}}

UUID of the tenant (required)

languageOptional

query string

en

Preferred language (optional)

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

X-API-KeyOptional

header string

{{api_key}}

Content-TypeOptional

header string

application/json

Responses

No response example is available for this endpoint yet.

Delete Return Request (Admin)

Delivery & Last-Mile / Return Requests

DELETE/delivery/returns/:id?tenant_id=&language=en

Delete a return request by ID.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request DELETE "$ONDI_BASE_URL/delivery/returns/:id?tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

idRequired

path string

return-request-uuid

Query parameters

tenant_idOptional

query string

Tenant ID (optional if in auth token)

languageOptional

query string

en

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Responses

Success200OK

Error - Not Found404Not Found

Approve Return Request (Admin)

Delivery & Last-Mile / Return Requests

POST/delivery/returns/:id/approve?tenant_id={{tenant_id}}&language=en

Approve a pending return request and create the return delivery using tenant setting return_requests (default service + destination mode). Payment Settings - Return delivery is created with payment_method = wallet and payer_type = sender (customer pays via wallet). Note: this endpoint has no request body; it is fully driven by settings.

Send a bearer token in Authorization and a tenant API key when the integration requires X-APIKey or X-API-Key.

Request

curl

1curl --request POST "$ONDI_BASE_URL/delivery/returns/:id/approve?tenant_id={{tenant_id}}&language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "X-API-Key: {{api_key}}" \4  --header "Content-Type: application/json"

Path parameters

idRequired

path string

return-request-uuid

Query parameters

tenant_idOptional

query string

{{tenant_id}}

UUID of the tenant (required)

languageOptional

query string

en

Preferred language (optional)

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

X-API-KeyOptional

header string

{{api_key}}

Content-TypeOptional

header string

application/json

Responses

Success200

Response body

json

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