Returns

1 API call in this section.

Request Return

Customer Portal / Delivery Management / Returns

POST/customer/delivery/returns

Creates a shop-requested return for an order owned by the authenticated customer portal user. The original delivery must be delivered; there is no time limit and no approval step. A commercial reverse delivery is created with its own delivery code and delivery_flow=commercial_return on the logical return root. For a staged return, the parent carries this classification and its child legs keep their existing operational flow behavior. The original-to-return relationship remains in return_requests.

Payer roles are the return delivery's actual roles and are stored and returned unchanged: the customer is sender and the shop is receiver. Allowed request combinations:

payer_type=receiver, payment_method=wallet: shop wallet
payer_type=receiver, payment_method=cash: shop cash
payer_type=sender, payment_method=cash: customer cash
Sender wallet is rejected. Shop wallet is settled during commercial-return activation through receiver_user_id, and successful creation returns payment_status=paid. Goods COD/refund is not part of this endpoint; the created return always has cod_amount=0.

Optional overrides

package_item_ids: selected IDs from the original delivery. When omitted, all original package items are copied. An explicitly supplied array must be non-empty and all IDs must belong to the original delivery. The return unit size is calculated from the selected items. When the original delivery has no package items or package details, its existing unit_size is preserved; the return service's unit_max is never used as the return quantity fallback.
collection_location: when omitted, uses the original customer/dropoff address.
return_location: when omitted, uses the original shop/pickup address.
notes

Frontend integration contract

Show the action only when order return_eligible=true.
Load services with GET /customer/delivery/services?purpose=return.
Calculate the displayed fee with POST /customer/delivery/price and body purpose=return, using collection coordinates as pickup and shop coordinates as dropoff.
Ask for payer and payment method separately. Send receiver when the shop pays and sender when the customer pays. Offer Wallet or Cash for the shop and Cash only for the customer.
On HTTP 201, use data.return_delivery.delivery_code and continue tracking from the original order detail. data.return_delivery.payer_type matches the submitted value, and data.return_delivery.payment_status confirms wallet settlement.
Treat delivery_flow=commercial_return as the shop-requested return classification. Keep using original_delivery_id and original_delivery_code for the relationship to the original order.
On 400/403/409, display localized message and use code only for branching.

Headers

Parameter	Type	Description
`Authorization`	string	Example: `Bearer {{access_token}}`
`Content-Type`	string	Example: `application/json`

Body parameters

Parameter	Type	Description
`delivery_id`Required	string	—
`delivery_service_id`Required	string	must be active, customer-accessible, portal-allowed, and `allow_returns=true`
`return_reason`Required	string	—
`notes`	string	—
`payer_type`Required	string	—
`payment_method`Required	string	—
`package_item_ids`	array<string>	—
`collection_location`	object	—
`collection_location.full_address`	string	—
`collection_location.latitude`	number	—
`collection_location.longitude`	number	—
`collection_location.country`	string	—

Show 11 more body fields

Additional body parameters

Parameter	Type	Description
`collection_location.contact_info`	object	—
`collection_location.contact_info.name`	string	—
`collection_location.contact_info.phone`	string	—
`return_location`	object	—
`return_location.full_address`	string	—
`return_location.latitude`	number	—
`return_location.longitude`	number	—
`return_location.country`	string	—
`return_location.contact_info`	object	—
`return_location.contact_info.name`	string	—
`return_location.contact_info.phone`	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/customer/delivery/returns" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "delivery_id": "original-delivery-uuid",6  "delivery_service_id": "return-enabled-service-uuid",7  "return_reason": "Customer requested return",8  "notes": "Call before collection",9  "payer_type": "receiver",10  "payment_method": "wallet",11  "package_item_ids": [12    "original-package-item-uuid"13  ],14  "collection_location": {15    "full_address": "Customer address",16    "latitude": 36.1911,17    "longitude": 44.0092,18    "country": "IQ",19    "contact_info": {20      "name": "Customer",21      "phone": "+9647000000000"22    }23  },24  "return_location": {25    "full_address": "Shop address",26    "latitude": 36.2,27    "longitude": 44.02,28    "country": "IQ",29    "contact_info": {30      "name": "Shop",31      "phone": "+9647500000000"32    }33  }34}'

Response examples

201Created

Response body

json

1{2  "success": true,3  "message": "Return request created successfully",4  "data": {5    "return_request": {6      "id": "return-request-uuid",7      "status": "approved",8      "requested_at": "2026-08-21T10:00:00.000Z",9      "requested_by_user_id": "shop-user-uuid",10      "request_source": "customer_portal"11    },12    "original_delivery": {13      "id": "original-delivery-uuid",14      "delivery_code": "DEL1001",15      "return_status": "return_approved",16      "return_delivery_code": "DEL1050"17    },18    "return_delivery": {19      "id": "return-delivery-uuid",20      "delivery_code": "DEL1050",21      "status": "pending",22      "payment_status": "paid",23      "delivery_flow": "commercial_return",24      "delivery_fee": 5000,25      "payer_type": "receiver",26      "payment_method": "wallet"27    }28  }29}

Request Return​