Parcel statuses: full reference for merchants

Purpose#

Every parcel has one status that tells you where it is on its journey. This page lists the statuses you may see in the merchant panel with their exact names, what each one means, who changes it and the usual order. The panel shows the Arabic names by default; the English names appear when the interface language is switched to English.

Who sees the status and who changes it#

A merchant sees the status of their own parcels only, and cannot change it from the panel: any attempt to change a status from the merchant panel is rejected with a 403 (forbidden) response. A status is changed by:

• The delivery company's staff, from the parcel and dispatch pages.
• The courier, in the mobile app, on the parcels assigned to that courier only.
• The external shipping company, when the parcel was handed to one: its statuses arrive and are converted into platform statuses.
• The system, when the parcel is created.

A merchant who runs the My delivery company section records the delivery outcome themselves for parcels delivered by their own couriers.

Where the status appears#

• My parcels: a coloured badge in the Status column of each row, and five tabs with a count of your parcels beside each. The counts cover all of your parcels and ignore the search and date filters.

• Parcel details page: the badge beside the tracking number, and the Parcel history card listing every change with its date, time and note, newest first. Delivery attempts appears only once the count is above zero, that is after a delivery was rescheduled or after a failed attempt sent the parcel back to Received Warehouse; a parcel delivered at the first attempt does not show it. For a parcel at an external shipping company, Status at company shows the status the company reported.
• Public tracking page: shows the status on a four-stage bar, with the status history below it (see the tracking article).
• API: GET /api/v1/parcels/{tracking} returns status_code (the number in the tables below), status_label and stage. The list GET /api/v1/parcels accepts a stage filter with one of pending, out_for_delivery, delivered, partially_delivered, returning, returned. The stage field takes one of these six values according to the status group (for example Delivery Man Assign and Delivery Re-Schedule carry out_for_delivery). A parcel waiting for balance carries awaiting_funds: the list hides such parcels, so you see this value in the response of the create call (sent with wait_for_balance=true) and when you fetch that parcel by its tracking number. Statuses that fit none of the six groups, such as Received Warehouse, Transfer to hub, Received by hub and the three pickup statuses, carry processing. The API needs an API key and, when the platform offers merchant plans, a plan that includes the API feature; it is not available to merchants of a delivery company.

Statuses in the usual order#

Preparation and pickup

Delivery

Return

The practical details of returns and refusals are in the "Returns and refusals" article.

The usual paths#

• Normal path: Received Warehouse → (Transfer to hub → Received by hub) → Delivery Man Assign → Delivered. A parcel you create from your panel moves to Received Warehouse as soon as the fee is deducted, so its status badge normally never shows Pending or the three pickup statuses. The Parcel history still contains a Pending entry for the creation (note such as "Parcel created (web)") next to the Received Warehouse entry.
• Pickup path (when a parcel starts as Pending): Pending → Pickup Assign → (Pickup Re-Schedule) → Received By Pickup Man → Received Warehouse.
• Another attempt: when the parcel is not delivered (the recipient refuses or cannot be reached) the courier records it, the parcel goes back to Received Warehouse, the attempt count goes up, the reason is recorded in the company's refused-parcels list, and the company assigns a courier again. This is not a final failure.
• Return: Return to Courier → Return assign to merchant → (Return assign to merchant Re-Schedule) → Return received by merchant.
• Parcels at an external shipping company: they become Received Warehouse after they are sent successfully, and then the platform converts the company's statuses using the status map set up for that company; some stages may be skipped. A "delivery failed" report from the company is only written as a history note, without changing the status. If the company cancels the shipment before receiving it, everything deducted is returned to you and the message "The shipment was cancelled and the amount was refunded to you." is shown.
• Final statuses: Delivered, Partial Delivered, Return received by merchant. After these the parcel only moves if the company's management explicitly cancels the step, which takes it one step back.

Labels that exist but the current workflow does not set#

These labels are defined in the system, but no transition in the current workflow leads to them, so do not expect to see them on new parcels.

• Legacy labels: 10 "Deliver", 11 "Return Warehouse", 12 "Assign Merchant", 13 "Returned Merchant". The "Returned / failed" tab counts the last three; the first appears only under "All".
• Cancel labels: 14 "Pickup Assign Cancel", 15 "Received By Pickup Man Cancel", 16 "Received Warehouse Cancel", 17 "Delivery Man Assign Cancel", 18 "Delivery Re-Schedule Cancel", 20 "Transfer to hub cancel", 21 "Received by hub cancel", 22 "Delivered Cancel", 23 "Pickup Re-Schedule Cancel", 25 "Return to courier cancel", 28 "Return assign to merchant Re-Schedule Cancel", 29 "Return assign to merchant cancel", 31 "Return received by merchant cancel", 33 "Partial Delivered Cancel".

When the company's management cancels a step, the parcel goes back to the previous status and the cancelled step is detached from the parcel, so it no longer appears in your Parcel history (the company's staff still see it in their own history).

What you can do in each status#

• Edit the parcel (the Edit button): the button is shown only in Pending. If you open the edit page directly (for example from a saved link) for a parcel in any other status, the panel sends you back to My parcels with the error "You can't edit this!".
• Delete the parcel (the Delete button): only in Pending and Received Warehouse, and only if the parcel was not sent to an external shipping company. The parcel is deleted and everything deducted is returned to you.
• Cancel shipment (on the details page): currently offered only for Sham Express shipments that the carrier's branch has not received yet (the status at the company is empty or PENDING); everything deducted is returned to you.
• Print the label, copy the tracking link and copy to a new parcel: available in any status.

Common mistakes#

• "Pending" and the parcel does not move: open Parcel history. If you find "Awaiting balance top-up: required …", your wallet does not cover the fee. Top it up and the platform completes the parcel automatically; the balance check runs hourly. If the balance is still short after 24 hours, the platform marks the order as expired (an internal state the panel does not display) and stops processing it: in the panel it stays listed as Pending and a later top-up will not complete it, so top up before the 24 hours end.
• Reading "Return to Courier" as the parcel reaching you: it does not. The parcel is still with the company and the return journey starts from there. The last status is "Return received by merchant", when it actually reaches you.
• Looking for a status called "Cancelled": there is no such status for the merchant. Deleting the parcel before it leaves for delivery removes it from the list and returns the amount.
• History notes in a language other than the interface: system notes are stored as text when the event happens, so they may appear in a different language from your current interface.

Limits and permissions#

• A merchant cannot change a status and sees only the parcels of their own account.
• The system rejects any transition that is not in the allowed-transitions map (for example a "Pending" parcel cannot be marked delivered directly). The exception is parcels at an external shipping company: their statuses are accepted even when they skip stages, unless the parcel is already in a final status.
• A courier changes only the parcels assigned to them, while they are in "Delivery Man Assign", "Delivery Re-Schedule" or the return-to-merchant stage.
• Cancelling steps is reserved for the company's management and staff.
• Badge colours: green for full and partial delivery, red for the four return statuses, and other colours by stage for the rest; the name is the reference, not the colour.