Returns and refusals: what happens and what to do

Purpose#

When a recipient refuses a parcel or delivery fails, the parcel is either attempted again or returned to you along a defined return path. Here is what you see, what to do and what happens to your balance.

Who does what#

• The courier records in the mobile app that the parcel was delivered, partially delivered, could not be delivered this time (for example the recipient refused) or failed for good.
• The company's staff record the return steps (assigning a courier, rescheduling, confirming your receipt) and need the parcel_status_update permission. At an external shipping company the return statuses come from that company.
• You cannot refuse, return or change a status from the panel (such an attempt gets a 403 response). A merchant who runs My delivery company records these outcomes for their own parcels.

What you need#

An active subscription, like the rest of the panel (a platform merchant needs a current plan when the platform offers plans; a merchant of a delivery company needs the company's subscription).

Another attempt or a return?#

A reason typed by the courier appears as a note on the "Received Warehouse" entry in Parcel history; otherwise that entry has no note. The system sets no limit on attempts; the company decides when to declare the final failure.

The return path#

Return to Courier → Return assign to merchant → (Return assign to merchant Re-Schedule) → Return received by merchant.

All appear under the Returned / failed tab of My parcels. The company records the receipt (your panel has no confirm button) and "Return received by merchant" is final. On the recipient's tracking page, return statuses keep the third stage ("With courier, on the way") as the current stage, show a red "!" icon beside the status name at the top of the card, and print "Delivery failed — the sender or delivery company will contact you." under the stage bar, without the reason.

What to do#

1. Follow the return

   Open My parcels and the Returned / failed tab. The notification is a push message to your device only: if push sending is set up on the platform and a device of yours is registered (the mobile app or the browser), and the notification center has not switched it off, you get a notification titled «طرد مرتجع» (Arabic by default) with the tracking number and the new status name, sent when the status changes to "Return to Courier", "Return assign to merchant" or "Return received by merchant". It does not appear in the panel's notification bell. If "Return received by merchant" appears and nothing reached you, contact the company or open a support ticket. With the Webhooks plan feature and an endpoint, outgoing webhooks send parcel.returning and parcel.returned.

2. Read the parcel history

   Open Parcel history: it shows the date of each attempt and the courier's note, which holds the reason if one was typed. In the panel the reason is not a separate field: it is that note on the history entry (the Parcel Logs page, opened from the row menu of the old view of My parcels that the "Old view" link under the list leads to, prints the same note); API users get it in events[].note from GET /api/v1/parcels/{tracking}.

3. Check your wallet

   Open My wallet. Platform merchants: open Transaction history and look for a "Parcel delivery failed" entry with the parcel's number; no entry means the rule refunds nothing. Merchants of a delivery company: open the Transactions table of "My wallet at …" and look for "Fee refund" (credited back) or "Return fee" (deducted from Collection) with the parcel's number; no entry means that amount was zero.

Expected result: you can follow the return and see its effect on your balance in your wallet history.

What happens to your balance#

A returned parcel collects nothing, so nothing is added to COD dues. The fee depends on how the parcel was shipped; the administration sets the percentages and you see the result as a history entry.

• A shipping company through the platform's account, or an independent delivery company whose fee was deducted at creation: at "Return to Courier" the platform credits back to Shipping balance a percentage of the delivery cost and of the platform fee (by default 100% and 0% respectively, unless the administration changed them). If the recipient was to pay the fee and the refund is below 100%, the unrefunded part is deducted from Shipping balance.
• A shipping company through your own account: the guarantee held in Reserved amounts is deducted permanently (it goes to the platform) instead of returning to you, while the rule's platform-fee percentage is refunded to Shipping balance.
• Your own company ("My delivery company"): only the platform fee can come back, by the rule's fee-refund percentage (0% by default, so nothing is refunded unless the administration raised it).
• A merchant of a delivery company: your wallet is with the company ("My wallet at …"), which sets what share of the fee comes back when your parcel is returned undelivered (0% by default). It returns to your balance there ("Fee refund") or, if the fee is taken from the collection, the unrefunded part is deducted from Collection ("Return fee").

Common mistakes#

• Reading "Received Warehouse" after a failed attempt as a return: it is another attempt. The return starts at "Return to Courier".

Limits and what the system does not do#

• A merchant cannot refuse a delivery, return a parcel or change its status; you can only delete a parcel (panel) or cancel it (POST /api/v1/parcels/{tracking}/cancel) while it is "Pending" or "Received Warehouse" and not sent to an external shipping company, which refunds the creation charge (otherwise not_cancellable, 409). For Sham Express shipments the carrier's branch has not received yet there is also Cancel shipment.
• The API and outgoing webhooks need the API and Webhooks plan features (when the platform offers plans) and are unavailable to merchants of a delivery company.
• There is no separate returns wallet: COD dues holds collections only. What a return costs you appears as the part of the fee that is not refunded, the forfeited Reserved amounts (a shipping company through your own account), or a "Return fee" or "Fee refund" line in the company wallet (a merchant of a delivery company); see "What happens to your balance".