Parcel warehouse statuses

Purpose#

The word "warehouse" appears in two different places in the platform. The first is a step in every parcel's journey: the parcel status Received Warehouse, meaning the parcel is at the delivery company and ready to be given to a courier. The second is the optional Warehouse service, where pallets are reserved for merchants and a supervisor releases goods with parcels. This page lists every parcel status whose name mentions the warehouse, who changes it, which moves are allowed and what each one does to the parcel and the merchant. It then explains how the Warehouse service reads parcel statuses without adding any of its own.

Who needs it#

• Company staff and dispatchers, who move parcels on the parcel pages and the dispatch board.
• Warehouse supervisors, whose outgoing list is built from these statuses.
• Developers, who read status_code 5 and the stage processing in API answers and webhooks.
• Merchants, who see the status and may delete a parcel while it is in this status.

The statuses#

The current return path does not pass through the warehouse: after a failed delivery a parcel goes Return to Courier, then Return assign to merchant, then Return received by merchant. The three legacy statuses stay in the code for old records, labels, filters and reports (the merchant's Returned / failed tab and the returned group of the reports include them).

How a parcel gets to Received Warehouse#

• At creation (the system). After the fare is charged, a parcel created through the platform's parcel creator (merchant panel, API, connected stores, merchant Excel import, company staff) moves from Pending to Received Warehouse at once. A parcel sent to an external shipping company moves there when the company accepts it. A parcel waiting for the merchant's balance stays Pending and hidden until the balance is topped up.
• Company staff. On the company's own domain, the status menu of a parcel row offers Received Warehouse for parcels in Pickup Assign or Pickup Re-Schedule. It needs the parcel_status_update permission.
• The courier. In the mobile app, when delivery cannot be completed (for example the recipient refuses or cannot be reached), the courier sends the status Received Warehouse for a parcel assigned or rescheduled to them (the status-update action of the courier app, with status_action set to 5). This is "back to warehouse", not a final failure.
• The dispatch board. On the dispatch board, Postpone returns a parcel that is with a courier to the warehouse; in the parcel list of a merchant who runs their own delivery company the same action is labelled Return to warehouse.
• The company API. The Company API (see its reference article) accepts the actions received (into the warehouse) and reschedule (back to the warehouse). Parcels at an external shipping company are refused with 409 and not_allowed.

Receive a parcel at the warehouse (company staff)#

1. Open the parcel list

   On the company's own domain open Parcels, then All parcels (this needs the parcel_read permission). The status column with its caret button appears only for accounts with the parcel_status_update permission, and not for Delivered, Partial Delivered or Return received by merchant parcels.

2. Open the status menu of the row

   The menu lists only the actions allowed for the parcel's current status. For a parcel in Pickup Assign or Pickup Re-Schedule it includes Received Warehouse.

3. Choose the branch and add a note

   The window is titled with the status name and has a required Branch field (the parcel's branch is preselected when it has one) and a Note field.

4. Save

   Press Save. On success a confirmation message appears. Without a branch a message tells you that the required fields are missing. The parcel is now ready for assignment.

Allowed moves#

For a parcel handled by the delivery company itself, the platform refuses any other move that involves Received Warehouse with a message that names both statuses (in Arabic: «لا يمكن نقل الطرد من حالة "…" إلى "…"»).

For a parcel in Received Warehouse the classic status menu shows three actions: Received Warehouse Cancel, Transfer to hub and Delivery Man Assign. The workflow also allows Return to Courier from this status (the company API action fail uses it), but the classic menu does not offer it. On the dispatch board these parcels appear in the Ready for distribution tab together with the parcels in Received by hub, where a courier is chosen by hand (for one parcel or for several selected parcels) or, when delivery areas are defined, by pressing Auto distribution by areas (Arabic: توزيع تلقائي حسب المناطق), which assigns each parcel to the least busy courier of its area.

Undoing Received Warehouse#

Received Warehouse Cancel applies to a parcel that is in Received Warehouse. It sends the parcel back to Received By Pickup Man, Pickup Re-Schedule or Pickup Assign according to the parcel's history, and detaches the Received Warehouse entry from that history. A parcel that was created straight into the warehouse has no pickup history, so the undo fails with a message that names the two statuses and nothing changes; delete the parcel instead if it has to be withdrawn.

What the status does#

• On the parcel. Receiving it or sending it back clears the assigned courier; the branch is set when one is chosen. Going back to the warehouse adds one to the delivery attempts and records an entry (the parcel, the courier, the name of the user who acted and a reason, with a default text when none is given) in the refused parcels list, الطلبات المرفوضة (shown as "Rejected requests" in the English menu). These steps move no money: the fare is charged when the parcel is created.
• For the merchant. The parcel shows Received Warehouse under the Being prepared tab and at the "in the warehouse" step of its progress bar. While the parcel is Pending or Received Warehouse, and was not sent to an external shipping company, the merchant can delete it (cancelling the parcel through the Merchant API does the same) and everything charged is refunded; once it is with a courier this is refused (the API answers 409 with not_cancellable). On creation, the notification-center event New parcel (Arabic «طرد جديد») goes to company staff by default; the merchant copy is off by default and is sent only if the platform operator turns it on. Later entries into the status send no dedicated notification from the notification center.
• For staff. Confirming the real weight in the staff app is allowed only while the parcel is in this status and is handled by the delivery company itself (not an external carrier); the fee difference is posted to the merchant's shipping balance.
• For developers. The API shows status_code 5, the label and the stage processing; the merchant's outgoing webhook receives parcel.status_changed (and parcel.created at creation) but no stage event. The company API list accepts stage=processing for it.
• For connected stores. The status becomes in_progress in Salla, ready in Zid, a confirmed fulfilment event in Shopify (when a fulfilment exists) and an order note in WooCommerce.

The Warehouse service and parcel statuses#

The Warehouse service (pallets, stock, supervisor panel) has no parcel status of its own; it reads the ordinary statuses.

• Outgoing list. A parcel appears under طرود طالعة (Outgoing parcels) in the supervisor panel when its pickup place is the warehouse, its status is Pending, Pickup Assign, Pickup Re-Schedule, Received By Pickup Man, Received Warehouse, Transfer to hub, Received by hub, Delivery Man Assign or Delivery Re-Schedule, it is not waiting for the merchant's balance and it has not been released. The list shows up to 300 parcels, oldest first.
• Release. Pressing سلّمته للمندوب (Handed to the courier) deducts the quantities (the products the merchant requested with the parcel, unless the supervisor types other quantities) from the stock, writes "out" movements and adds the parcel to the day's list طلعت اليوم (Released today). The parcel's status does not change, no courier is assigned and nothing is delivered.
• Reserved stock. Products requested with a parcel stay reserved while the parcel is in one of the statuses above and has not been released; available stock is the quantity on hand minus the reserved quantity. The reservation ends when the parcel is released or leaves those statuses.

Common mistakes#

• Looking for Return Warehouse after a failed delivery. The flow is Return to Courier, Return assign to merchant, Return received by merchant. Return Warehouse, Assign Merchant and Returned Merchant remain only on old parcels and in labels.
• Expecting the supervisor's release to change the status. It only records goods leaving; the courier is assigned in the dispatch step.
• Undoing the warehouse step of a new parcel. It fails because there is no earlier step to return to.
• Treating processing as one status. In the API processing also covers the pickup statuses, Transfer to hub and Received by hub; use status_code 5 for the warehouse.

Limits and permissions#

• Receiving at the warehouse and undoing it are staff actions that need the parcel_status_update permission (plus parcel_read to open the parcel list they start from), and staff only reach their own company's parcels. A courier can send a parcel back only when it is assigned to them and is in Delivery Man Assign or Delivery Re-Schedule. A merchant cannot change a status from the merchant panel (403); a merchant who runs their own delivery company changes statuses only for that company's parcels.
• Parcels at an external shipping company take their statuses from the carrier: any move is accepted unless the parcel is in a final status, so such a parcel can also move into or out of the legacy statuses if the carrier's status map says so. The exception is Return to Courier: from it such a parcel can only go to Return assign to merchant or Return received by merchant (or be undone with the normal undo moves). The company API refuses to change these parcels.
• Delivered, Partial Delivered and Return received by merchant are final: nothing leaves them except an explicit cancel by company management.