Parcel lifecycle in the company panel

Purpose#

This page explains how a parcel moves through the company panel: the statuses it can have, who may move it, and what each move triggers. All delivery and return moves are checked against one transition map, and a move that is not on the map is rejected.

Who can change what#

Undo steps (called "cancel" in the menus) are limited to company management: admin, in-charge, hub and super admin.

The normal path#

Delivery outcomes#

• Delivered: a delivery can carry a note, and the courier app can also attach a photo and a signature. This is a final status.
• Partial Delivered: you enter the amount actually collected, which cannot exceed the parcel's COD amount. Also final.
• Back to the warehouse: when the courier cannot deliver (refusal, not home), the parcel returns to Received Warehouse with no courier, one more delivery attempt and a reason on the Rejected requests page. It is not a failure.
• Return to Courier: a final delivery failure. The parcel enters the return path and the fee refund rules apply (see the article on COD and fees).

The return path#

Return to Courier, then Return assign to merchant (a courier may be assigned), optionally Return assign to merchant Re-Schedule, then Return received by merchant, which is final. If a parcel is marked received by the merchant without having gone through Return to Courier, the failure is still recorded once.

Status log#

Parcel Logs on each parcel shows a five-step progress bar (Pending, In Progress, Warehouse, Deliveryman Assigned, then Delivered; for return statuses and Partial Delivered the last step reads "Return Courierr", because the page prints a stray trailing "r") and a timeline of every entry with its date, time, hub or courier and note. Undone steps stay in the timeline, mostly with a "Canceled" badge. The parcel list has a View Proof of Delivery column with a View button for Delivered parcels (not for Partial Delivered). These labels appear in English even in the Arabic interface.

Undoing a step#

The undo options in the status menu move the parcel back one step, mark the undone entry as cancelled and reverse its financial effect; undoing Return to Courier reverses the failure posting. They exist for the pickup, warehouse, hub, courier-assignment, Return to Courier and return-to-merchant steps. However, Received Warehouse Cancel works only for a parcel that went through a pickup step, and returns it to that pickup status; a parcel created in the normal way went straight from Pending to Received Warehouse, so the undo fails with the invalid-transition message (see Limits). Parcels that are Delivered, Partial Delivered or Return received by merchant show no Status Update menu in the list.

What each change triggers#

After a change commits in the checked workflow (courier assignment and re-scheduling, delivery, return, receiving at the warehouse, and the undo steps for Return to Courier and return to merchant), the system pushes the status to linked store orders, to Zid orders and to the older Store Syria sync (for parcels created through that integration), sends the merchant's outgoing webhook if enabled, and sends notifications according to the notification-center rules. Store orders (WooCommerce, Shopify, Salla) are updated only when the store connection has Send shipment status back to the store ticked, and not every change reaches the store: Shopify receives fulfilment events for out for delivery, delivered, failure (Return to Courier) and confirmed (Received Warehouse); WooCommerce gets an order note for each change and the order is marked completed on delivery; Salla receives only the statuses it has an equivalent for; Zid receives only three: ready (warehouse receipt, hub transfer or hub receipt), in delivery (courier assignment) and delivered. The older pickup, hub-transfer and receive-by-hub steps (see Limits) do not run the sync-and-notification step that follows a checked change: no push to store orders or to Zid from the application, no merchant webhook and none of the standard status notifications, and neither do the undo steps for pickup, hub transfer, receive by hub, courier assignment, delivery re-schedule and warehouse receive. The pickup, received-by-pickup-man, hub-transfer and receive-by-hub steps and the undo steps for pickup assignment and pickup re-schedule only run the older Store Syria sync. Whether Zid receives these statuses depends on a database trigger that is not part of the application code. Pickup assignment sends its own pickup notification to the pickup man and the merchant (plus SMS to them when ticked); pickup re-schedule sends direct push notifications to the pickup man and the merchant (plus optional SMS). The public tracking page groups the statuses into four steps (see the article on tracking).

Shipping-company parcels#

Parcels sent to an external shipping company take their statuses from that company, and statuses may skip stages, except out of a final status; from Return to Courier only Return assign to merchant or Return received by merchant is accepted.

Limits and permissions#

• The Parcel distribution page is open to all company staff; it is not gated by parcel_status_update.
• Pickup, hub-transfer and receive-by-hub steps, and the undo steps for pickup, hub transfer, receive by hub, courier assignment, delivery re-schedule and warehouse receive, use an older code path that writes the status directly, without the transition check. Courier assignment, re-scheduling, delivery, return and receiving at the warehouse use the checked path, and so do the undo steps for Return to Courier and return to merchant.
• A courier cannot act on a parcel that is not assigned to them: the message is "This parcel is not assigned to you".
• A change that is not allowed fails with a message naming both statuses. In Arabic it reads «لا يمكن نقل الطرد من حالة "أ" إلى "ب"»; the English interface shows irregular punctuation, for example Cannot move the parcel from status Delivered» to «Pending".