Delivery Companies & Drivers

A Delivery Company is a logistics partner that operates a fleet of Drivers and earns the delivery fee of every order it successfully delivers (and of every order it attempts — see Failed delivery below). The fee lands in the company's wallet, denominated in the platform base currency, and is later paid out through a settlement.

Actors

Actor	What they do
Platform Admin	Approves orders, then assigns each approved order to a delivery company.
Delivery Company admin / staff	Assigns one of their own drivers to each order handed to the company.
Driver	Starts the trip, then marks the order delivered or failed from the mobile app.

Onboarding

NQLA registers your company with one primary responsible user plus any number of staff users.
You register your Drivers — each gets their own login. A driver's license and national ID are stored encrypted at rest.
Your company wallet starts at zero; it is credited automatically as you complete deliveries.

Daily delivery flow

Admin → company. An Admin assigns an approved order to your company. The order status becomes assigned_to_delivery and delivery_company_id is stamped on it.
Company → driver. You (or an Admin) assign one of your own drivers. The platform rejects any driver who does not belong to your company. Status → assigned_to_driver.
Driver starts. The driver taps Start in the app. Status → out_for_delivery. Only the assigned driver can do this.
Driver closes the trip with one of:
- Delivered — status → delivered. Your wallet is credited the delivery fee, and the merchant's wallet is credited the order net.
- Failed — status → failed_delivery. The attempt still earns you the delivery fee (the merchant is charged delivery + commission), and the stock is restored to inventory.

A failed order can be re-assigned to a driver and retried — see Edge cases.

What drivers do on mobile

The driver app talks to /api/v1/driver/deliveries:

GET / — list my assigned deliveries (cursor-paginated; follow next_cursor).
GET /{order} — view one order (only my own).
POST /{order}/start — start delivery.
POST /{order}/delivered — mark delivered.
POST /{order}/failed — mark failed (optional notes).
POST /{order}/location — post a GPS ping (rate-limited).
POST /{order}/review — submit a delivery review.

Every write is scoped to the authenticated driver — a driver can only act on orders where driver_id matches them.

Wallet & settlement

The delivery fee is credited once per order (idempotent — a retry never double-credits).
The credit is converted from the order currency into the base currency before it touches the wallet.
Balances are paid out via settlements; once a settlement is marked paid, each covered order is stamped with its settlement_id.

Screens & endpoints

Audience	Location	Gating
Delivery companies (admin)	`/admin/delivery-companies`	`manage_delivery_companies`
Drivers (admin)	`/admin/drivers`	`manage_drivers`
Assign order to delivery	`POST /admin/orders/{order}/assign-delivery`	`manage_orders`
Assign order to driver	`POST /admin/orders/{order}/assign-driver`	`assign_orders_to_driver`
Driver mobile API	`/api/v1/driver/deliveries`	`update_delivery_status`

Orders Lifecycle (orders-lifecycle) — the full order state machine.
Storage Companies & Warehouses (storage-companies-warehouses).