Create, list, and track deliveries.
Deliveries
Deliveries
Create Delivery (on-demand)
Creates an immediate on-demand delivery. For PREPAID merchants the wallet is debited at the moment of booking.
POST /api/v1/deliveries
Content-Type: application/jsonRequest body
{
"customerName": "Ahmed Ali",
"customerNumber": "99887766",
"pickupLatitude": 29.3764,
"pickupLongitude": 47.9785,
"deliveryLatitude": 29.3117,
"deliveryLongitude": 48.0034,
"deliveryAddress": ["Kuwait", "Salmiya", "Block 3", "Street 1", "House 12"],
"collectCash": false,
"totalAmount": "0.000",
"specialNotes": "Leave at reception",
"vehicleType": "bike"
}Required fields
| Field | Description |
|---|---|
customerName | Recipient full name |
customerNumber | Recipient phone number |
pickupLatitude | Pickup GPS latitude (alias: fromLatitude) |
pickupLongitude | Pickup GPS longitude (alias: fromLongitude) |
deliveryLatitude | Drop-off GPS latitude (alias: toLatitude) |
deliveryLongitude | Drop-off GPS longitude (alias: toLongitude) |
Optional fields
| Field | Default | Description |
|---|---|---|
deliveryAddress | Auto from coords | String array — address parts |
pickupAddress | — | Pickup address label |
pickupName | — | Override pickup contact name |
pickupNumber | — | Override pickup contact phone |
alternateCustomerNumber | — | Secondary recipient phone |
additionalAddressDetail | — | Apartment/floor details |
branchId | — | Optional branch reference |
collectCash | false | Enable cash-on-delivery |
totalAmount | "0.000" | COD amount in KWD |
specialNotes | — | Driver instructions |
vehicleType | "bike" | bike, car, or van |
customPickup | false | Custom pickup flag |
quotedPrice | — | Optional price hint |
Response 201
{
"delivery": {
"id": "clx...",
"orderNumber": "FLH4001",
"status": "PENDING",
"customerName": "Ahmed Ali",
"estimatedPrice": "2.500",
"driverName": null,
"isScheduled": false,
"createdAt": "2026-06-14T01:33:00.000Z"
}
}💡 Save the delivery ID
Store delivery.id — you'll need it to poll status with the Get Delivery endpoint.
Create Delivery (with COD)
Same endpoint. Set collectCash: true and provide totalAmount.
{
"customerName": "Sara Mohammed",
"customerNumber": "66554433",
"pickupLatitude": 29.3764,
"pickupLongitude": 47.9785,
"deliveryLatitude": 29.2800,
"deliveryLongitude": 48.0500,
"deliveryAddress": ["Kuwait", "Hawally", "Block 5"],
"collectCash": true,
"totalAmount": "15.750",
"specialNotes": "Collect cash on delivery"
}Create Delivery (scheduled)
Set isScheduled: true and include scheduledDeliveryAt.
{
"customerName": "Ahmed Ali",
"customerNumber": "99887766",
"pickupLatitude": 29.3764,
"pickupLongitude": 47.9785,
"deliveryLatitude": 29.3117,
"deliveryLongitude": 48.0034,
"isScheduled": true,
"scheduledDeliveryAt": "2026-07-01T10:00:00.000Z",
"specialNotes": "Ring doorbell",
"vehicleType": "bike"
}Schedule rules
- Must be at least 30 minutes from now
- No more than 14 days ahead
- Scheduled delivery must be enabled on your account (
available: truein/api/v1/scheduled-delivery)
⚠️ Check availability first
Call GET /api/v1/scheduled-delivery before booking to confirm scheduled delivery is enabled for your account.
List Deliveries
GET /api/v1/deliveries?limit=20&status=PENDINGQuery parameters
| Parameter | Default | Description |
|---|---|---|
limit | 50 | Max results, 1–100 |
status | — | Filter by status |
Response:
{
"deliveries": [
{
"id": "clx...",
"orderNumber": "FLH4001",
"status": "DELIVERED",
"customerName": "Ahmed Ali",
"estimatedPrice": "2.500",
"driverName": "Mohammed",
"driverPhone": "99112233",
"isScheduled": false,
"createdAt": "2026-06-14T01:33:00.000Z"
}
]
}Get Delivery by ID
Use this to poll the status and driver assignment of a specific delivery.
GET /api/v1/deliveries/:idResponse:
{
"delivery": {
"id": "clx...",
"orderNumber": "FLH4001",
"status": "ENROUTE",
"customerName": "Ahmed Ali",
"customerNumber": "99887766",
"deliveryLatitude": 29.3117,
"deliveryLongitude": 48.0034,
"estimatedPrice": "2.500",
"driverName": "Mohammed",
"driverPhone": "99112233",
"vehicleType": "bike",
"statusHistory": [
{ "status": "PENDING", "timestamp": "2026-06-14T01:33:00.000Z" },
{ "status": "ACCEPTED", "timestamp": "2026-06-14T01:34:12.000Z" }
],
"isScheduled": false,
"collectCash": false,
"createdAt": "2026-06-14T01:33:00.000Z",
"updatedAt": "2026-06-14T01:40:00.000Z"
}
}Order statuses
| Status | Description |
|---|---|
PENDING | Delivery booked, awaiting dispatch |
REQUESTED | Driver request sent |
ACCEPTED | Driver accepted |
INPROGRESS | Driver heading to pickup |
PICKEDUP | Order collected |
ENROUTE | Driver heading to customer |
DELIVERED | Delivery complete ✓ |
CANCELLED | Cancelled |
REJECTED | No driver available |
FAILED | Delivery failed |