Add and manage couriers in the company panel

Purpose#

Couriers carry parcels to recipients and collect cash on delivery. This guide covers adding a courier, setting their commission and areas, controlling whether they receive parcels, and what they then do in the mobile app.

Who can use it#

Company admin, in-charge and hub accounts use Couriers and commissions in the side menu. A merchant who runs their own delivery company gets the same page in the merchant panel. The older Delivery Man menu entry needs the delivery_man_* role permissions (read, create, update, delete).

Requirements#

• A mobile number that no other account on the platform uses.
• An active company subscription and room in its courier limit; some companies are exempt. At the limit New courier is disabled and a note shows: "Your company plan allows N couriers, and you have M. Upgrade the plan."
• A merchant's own delivery company is limited by the merchant plan's courier count instead: "You do not have an active merchant plan subscription — subscribe or renew to add couriers." or "Your plan allows N couriers, and you have M. Upgrade the plan to add more couriers."
• Optional: draw your delivery areas first on the Delivery areas page.

Add a courier#

1. Open the couriers page

   In the side menu choose Couriers and commissions (page title My company couriers).

2. Click New courier and fill in the details

   • Name and Mobile number (both required; digits only, 9 to 15, unique on the whole platform).
   • Email (optional, unique if given).
   • Password: required for a new courier, at least 6 characters. The key button generates one and the eye button shows it.
   • Parcel limit with it: the most undelivered parcels the courier can carry at once; 50 if left empty.
   • Status: "Active — receiving parcels" or "Suspended — not shown in assignment".

3. Set the commission

   Choose Percentage % or Fixed amount and a value. A percentage is taken from the delivery fee and cannot exceed 100. Leave the value empty to use your company's default percentage; enter 0 for no commission. The optional Failed attempt fee is added to the courier's commission when the delivery is marked as finally failed (status Return to Courier) for a parcel they hold. It is not paid when the parcel is only postponed or sent back to the warehouse.

4. Choose delivery areas

   Tick the areas the courier covers. If you have none yet the form says "No areas yet — Draw it on the map".

5. Save and hand over the login

   After saving, the courier's card shows a 6-digit login number. The courier signs in to the courier app with that number, the mobile number or the email, plus the password.

Expected result#

Each courier has a card with the name, phone, login number, an Active or Suspended badge, area chips, Holding / limit, the number delivered, Cash on hand and Their commission, and the buttons Edit, Settlement and Statement. Edit opens the same form; leave the password empty to keep it. Counters at the top summarise couriers, cash and commissions, and the list can be searched and filtered.

Hub and areas#

• A new courier is linked automatically to the company's first hub; there is no hub field here. The older Delivery Man form has a required Hub and legacy charge and balance fields that do not drive the commission above.
• On the Parcel distribution page, when delivery areas are defined and the recipient's map position falls inside one, that area's couriers are listed first in the parcel's courier list; the older dialog under All parcels does not order couriers by area. Auto-assign gives each ready parcel inside an area to that area's courier with the fewest parcels who is under the limit; parcels with no area are not auto-assigned.
• On the Parcel distribution page, assigning a parcel to a courier who has reached the limit is rejected with a message that starts with the parcel's tracking number: "Courier «name» reached the limit (a / b undelivered parcels)". In the older assignment dialog under All parcels, the courier search simply leaves out couriers who are at their limit, and the server does not re-check the limit there.

Online and offline#

A switch on the couriers page lets the company require couriers to press "online" in the app before they can receive parcels. While it is on, the Parcel distribution page lists an offline courier greyed out so they cannot be chosen, and auto-assign skips them. In the older dialog under All parcels the courier search leaves offline couriers out, and the server refuses to assign a parcel to them. Its label is in Arabic even in the English interface: "شرط «متصل» لاستلام الطرود" (meaning "require online status to receive parcels").

Suspending and deleting#

• Set Status to Suspended to stop assignments. The courier cannot sign in (the courier API refuses with “حساب المندوب موقوف — تواصل مع شركتك.”, an Arabic message with no English translation, meaning “Courier account suspended — contact your company.”), requests from existing sessions are refused with “Account suspended (status = 0).”, and the courier disappears from the assignment lists. Parcels already with them stay assigned until you reassign them.
• This page has no delete button; delete exists only in the older Delivery Man list. Deleting a courier also deletes their records and parcel-history entries, so prefer suspending.

What the courier does in the app#

• Signs in (10 attempts per minute at most) and sees the assigned parcels.
• Marks a parcel delivered, or partially delivered with the amount actually collected, which cannot exceed the parcel's COD amount.
• Switches online or offline, and sends their location when live tracking is allowed on your plan.

Collected amounts are added to Cash on hand until you record a settlement; the commission is added to Their commission for every delivered parcel.

Common mistakes#

• "This mobile number is used by another account on the platform."
• "The percentage must be between 0 and 100." or "Parcel limit must be at least 1."
• A courier who cannot sign in: check the login number or mobile, the password and the Suspended status.

Limits and permissions#

• Couriers are always scoped to your company: another company's courier answers "The courier does not exist or does not belong to your company."