Skip to main content

Returns

1 API call in this section.

Create Return Request​

External & Carrier Integrations / Returns
POST/external/returns?tenant_id={{tenant_id}}

Create a return request for a delivered delivery (Customer-only endpoint). External API Note: This endpoint accepts delivery_code (number) instead of delivery_id (UUID). The system resolves the delivery_code to delivery_id internally. Security: - This endpoint is customer-only. The authenticated user must be a customer. - The delivery must belong to the authenticated customer. Returns 403 if the delivery belongs to a different customer. Business Rules: - Delivery must be delivered status - Only one non-cancelled return request per delivery - Inserts return_requests with status pending and updates deliveries.return_status = return_requested - If tenant setting return_requests.auto_approval = true, system auto-approves and creates a return delivery using: - return_requests.default_delivery_service_id - destination rules via return_requests.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. Request Body: - delivery_code (number, required): The numeric delivery code - return_reason (string, required): Reason for the return - notes (string, optional): Additional notes Responses: - 201 success (pending or auto-approved) - 400 validation / not eligible / missing fields - 401 unauthorized (customer authentication required) - 403 unauthorized_delivery_access (delivery does not belong to customer) - 404 delivery_not_found / tenant_not_found

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/external/returns?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  "delivery_code": 12345,8  "return_reason": "Damaged product",9  "notes": "Package arrived with visible damage"10}'
Request body
json
1{2  "delivery_code": 12345,3  "return_reason": "Damaged product",4  "notes": "Package arrived with visible damage"5}

Query parameters

tenant_idOptional
query string

{{tenant_id}}

ID of the tenant (Required)

Request body fields

delivery_codeExample
number

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 - Pending201Created
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 Approved201Created
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 Found404Not Found
Response body
json
1{2  "success": false,3  "message": "delivery_not_found"4}
Error - Delivery Not Eligible400Bad Request
Response body
json
1{2  "success": false,3  "message": "delivery_not_eligible_for_return"4}
Error - Missing delivery_code400Bad Request
Response body
json
1{2  "success": false,3  "message": "field_required delivery_code"4}
Error - Unauthorized401Unauthorized
Response body
json
1{2  "success": false,3  "message": "unauthorized"4}
Error - Unauthorized Delivery Access403Forbidden
Response body
json
1{2  "success": false,3  "message": "unauthorized_delivery_access"4}