Skip to main content

Returns

1 API call in this section.

Create Return Request​

External & Carrier Integrations / Returns
POST/external/returns

Create a return request for a delivered delivery (Customer-only endpoint).

External API note

This endpoint accepts delivery_code instead of delivery_id (UUID). The system resolves the external delivery code internally. When auto-approved, return_delivery_id is also returned as the public return delivery code.

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 in delivered status.

  • Only one non-cancelled return request is allowed per delivery.

  • Inserts return_requests with status pending and updates deliveries.return_status = return_requested.

  • If tenant setting return_requests.auto_approval = true, the system auto-approves and creates a return delivery using return_requests.default_delivery_service_id and destination rules from 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.

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

Headers

ParameterTypeDescription
X-API-Keystring

Example: {{api_key}}

Content-Typestring

Example: application/json

Body parameters

ParameterTypeDescription
delivery_codeRequiredstring

External delivery code, for example DEL-000001.

return_reasonRequiredstring

Non-empty reason for the return.

notesOptionalstring

Additional customer note. Empty strings are treated as null.

Staging
Request
curl
1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/external/returns" \2  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "delivery_code": "DEL-000001",6  "return_reason": "Damaged product",7  "notes": "Package arrived with visible damage"8}'

Response examples

201Created
Response body
json
1{2  "success": true,3  "error": null,4  "message": "Return request created",5  "return_request_id": "return-request-uuid",6  "auto_approved": false7}