How a courier records cash on delivery and how it reaches the company settlement

Purpose#

The courier API has no separate endpoint for entering cash on a normal delivery: recording the delivery also records the cash the courier collected. This guide explains what is recorded for a full and a partial delivery, how the cash becomes a balance that the company settles, and the validation rules. The system only keeps accounts; it moves no real money.

Who can use it#

Courier accounts of a delivery company (including a merchant's private company), through the courier mobile API. The cash is then settled by company staff (admin, in-charge or hub accounts) on the Courier settlements page. That page requires only a staff account type, so it needs no special permission and no plan feature. For a merchant's private company, its owner settles from the المناديب والعمولات (Couriers and commissions) page under شركتي للتوصيل (My delivery company) in the merchant panel.

What you need#

• A signed-in courier: the apiKey header and a Bearer token (see the delivery workflow guide).
• A parcel assigned to you, in the status "Delivery Man Assign" (with courier) or "Delivery Re-Schedule" (rescheduled).
• The cash you actually received from the recipient.

Steps#

1. Check the amount to collect

   In the lists returned by the dashboard endpoint, each parcel shows cod_display (the amount in the currency the merchant used), cod_original and cod_currency, cod_amount2 (the amount in US dollars) and is_amount_collected. Once collected, cod_amount2 comes back empty.

2. Record a full delivery

   POST /api/v10/deliveryman/parcel/delivered/{id}. There is no amount field: the system records the parcel's whole amount to collect (cod_amount2, or the older cash_collection value when that is empty). A parcel with nothing to collect records no cash.

3. Record a partial delivery

   POST /api/v10/deliveryman/parcel/partial-delivered/{id} with cash_collection, the amount you actually received. Zero up to the full amount is accepted. The API does not convert currencies: the number is read as US dollars and compared with cod_amount2, so for a parcel priced in another currency send the dollar equivalent of what you received.

4. Check your cash balance

   GET /api/v10/deliveryman/payment-logs returns expense.current_balance, the cash you hold in US dollars, and expense.transactions, each with amount, operation_type (credit or debit), category, balance_after, date and parcel_details. For parcel entries parcel_details holds parcel_id, tracking_id and customer_name; for entries the company made when it recorded receiving your cash, it is filled from your courier record and shows "Unavailable" instead of a tracking ID, and it can be null on an entry with no reference.

1234

1. Each courier's cash and commission due
2. Choose the movement: receive cash or pay dues
3. Enter the amount
4. Save the movement

Expected result#

For a parcel delivered by a company courier the system records, once only:

• the collected amount added to your cash balance;
• your commission added to your commission balance: your own setting (a percentage of the delivery fee, or a fixed amount) or, if empty, the company's default percentage, with 0 meaning none. A final failure (status_action 24) can add the company's optional failed-attempt fee;
• the parcel marked as collected (is_amount_collected) with the collected amount stored.

Repeating the request cannot post it twice. Your cash balance falls only when the company records receiving the cash, or when staff undo the delivery.

How it reaches the company settlement#

On the تسوية المناديب (Courier settlements) page, each courier row shows نقدية بعهدته (Cash in their custody) and عمولاته المستحقة (Their commissions due). Staff choose استلمت نقدية منه (I received cash from them), enter an amount and an optional note (up to 500 characters) and press حفظ (Save). That reduces the courier's cash balance and cannot exceed it; otherwise the page shows «رصيد المحفظة غير كافٍ. المطلوب: X، المتاح: Y» (with the panel in English: "Insufficient wallet balance. Required: X, available: Y"). On this page amounts are US dollars and are not converted. On the owner's page the amount is entered in the owner's display currency and converted to US dollars. See the courier settlement guide.

In the usual cases the same delivery also updates the merchant's side:

Common mistakes#

• Sending a partial amount in Syrian pounds. It is read as dollars, so it is usually refused as above the parcel's amount.
• Sending text instead of a number. It is read as 0 and the partial delivery records no cash.
• Looking for an amount field on full delivery. If the recipient paid less, use partial delivery.
• Trying to undo a delivery. Only company staff can; the undo reverses these entries and can leave your cash balance negative.
• Reading profile, income-expense or parcel-payment-logs for cash. They read older statement tables; the current figures are in payment-logs.

Limits and permissions#

• Only the courier the parcel is assigned to can record a delivery; others get HTTP 422 with a message starting This parcel is not assigned to you.
• A partial amount must be 0 or more and not above the parcel's amount (a tolerance of 0.001). Violations return HTTP 422 with a message starting The collected amount cannot be negative or The collected amount exceeds the parcel COD amount. A missing cash_collection on partial-delivered/{id} returns The fields is required! unchanged.
• These rule errors repeat after a dash and end with a reference like (ref: E1A2B3); match on the HTTP status and part of the text.
• Settlement is done on the company side (staff, or the merchant owner of a private company); the courier cannot settle in the app.