Skip to main content

​
Overview

This page provides detailed descriptions for all fields in the delivery object returned by the API.

​
Core Identifiers

​
id
string (UUID)
required
Unique identifier for the delivery
  • Used for API calls and internal references
  • Automatically generated on creation
  • Example: "abc123-def456-ghi789"
​
trackingId
string
required
Human-readable tracking identifier
  • Shared with customers for tracking
  • 12-character alphanumeric string
  • Example: "CHI-ABC123"
​
userId
string (UUID)
required
ID of the user who created the delivery
  • Links to the API key owner
  • Used for authorization checks
​
driverId
string (UUID)
ID of the assigned driver
  • null if no driver assigned yet
  • Populated when driver accepts the delivery

​
Status & Type

​
deliveryStatus
enum
required
Current status of the deliveryPossible values:
  • PENDING - Created, awaiting payment or driver assignment
  • STARTED - Driver has accepted and started the delivery
  • PICKED-UP - Package picked up by driver
  • COMPLETED - Successfully delivered
  • CANCELLED - Delivery was cancelled
​
deliveryType
enum
required
Type of delivery servicePossible values:
  • SendDelivery - Standard delivery from point A to B
  • RequestPickup - Pickup request service
​
deliveryName
string
Optional custom name for the delivery
  • Helps identify deliveries in your system
  • Example: "Office Supplies", "Customer Order #1234"

​
Location & Route

​
pickupAddress
string
required
Full address of the pickup location
  • Human-readable format
  • Example: "123 Main Street, Victoria Island, Lagos"
​
pickupLatLong
object
required
Precise coordinates of the pickup location
​
destinationAddress
string
required
Full address of the delivery destination
  • Human-readable format
  • Example: "456 Business Avenue, Lekki, Lagos"
​
destinationLatLong
object
required
Precise coordinates of the destination
​
currentLocation
object
Driver’s current location during delivery
  • Only available when delivery is in progress
  • null when delivery is pending or completed
  • Updates in real-time via WebSocket
​
route
object
Calculated route information from pickup to destination

​
Contact Information

​
receiverPhoneNumber
string
required
Recipient’s phone number
  • Normalized to Nigerian format (234 prefix)
  • Example: "2348012345678"
​
senderPhoneNumber
string
required
Sender’s phone number
  • Normalized to Nigerian format (234 prefix)
  • Example: "2348087654321"
​
additionalNotes
string
Special delivery instructions
  • Visible to the assigned driver
  • Example: "Please call before delivery", "Leave at gate"

​
Payment & Pricing

​
deliveryAmount
number
required
Total delivery cost in Naira (₦)
  • Includes all fees and charges
  • Example: 2500 (₦2,500)
​
isPaid
boolean
required
Payment status
  • true if payment has been completed
  • false if payment is pending
​
transactionId
string
Payment transaction reference
  • Links to the payment record
  • Populated after successful payment

​
Package Information

​
packageImage
array
Photos of the package
  • Array of image objects
  • Uploaded by driver or sender
  • Used for proof of delivery

​
Timing & Schedule

​
scheduledTime
datetime
Scheduled delivery time
  • ISO 8601 format
  • null for immediate deliveries
  • Example: "2025-01-15T14:00:00.000Z"
​
pickedUpAt
datetime
When the driver picked up the package
  • ISO 8601 format
  • null until package is picked up
  • Example: "2025-01-15T10:30:00.000Z"
​
arrivedAtPickupLocationTime
datetime
When the driver arrived at the pickup location
  • ISO 8601 format
  • null until driver arrives
  • Example: "2025-01-15T10:15:00.000Z"
​
arrivedTime
datetime
When the driver arrived at the destination
  • ISO 8601 format
  • null until driver arrives at destination
  • Example: "2025-01-15T11:00:00.000Z"
​
createdAt
datetime
required
When the delivery was created
  • ISO 8601 format
  • Automatically set on creation
  • Example: "2025-01-15T10:00:00.000Z"
​
updatedAt
datetime
required
Last modification timestamp
  • ISO 8601 format
  • Updates automatically on any change
  • Example: "2025-01-15T10:45:00.000Z"

​
Driver Status

​
hasArrived
boolean
required
Whether the driver has arrived at the destination
  • Used for arrival notifications
  • true when driver reaches destination

​
Bulk Deliveries

​
bulk
string (UUID)
Bulk delivery group identifier
  • null for single deliveries
  • All deliveries with the same bulk ID are part of one bulk order
  • Used to group multiple deliveries from the same pickup location
​
order
number
Position in bulk delivery sequence
  • null for single deliveries
  • Determines the order for multi-stop routes
  • Example: 1, 2, 3 for first, second, third stops
​
orderCode
string
Order code for the delivery
  • Optional reference code for tracking
  • Can be used to link delivery to external order systems
  • null if not provided

​
Field Exclusions

The following fields exist in the database but are excluded from API responses for security and business logic reasons:
  • usesPromo - Internal promo tracking
  • promoPercentage - Internal pricing calculation
  • driverCut - Internal revenue split
  • companyCut - Internal revenue split
  • shop - Internal shop reference
  • vehicleDirection - Internal tracking
  • inActive - Internal flag
  • deliveryDate - Deprecated (use createdAt or scheduledTime)
  • deliveryTime - Deprecated (use timestamp fields)
  • pickupTime - Deprecated (use pickedUpAt)

​
Example Complete Delivery Object

{
  "id": "abc123-def456-ghi789",
  "trackingId": "CHI-ABC123",
  "userId": "user-uuid-123",
  "driverId": "driver-uuid-456",
  "deliveryStatus": "PICKED-UP",
  "deliveryType": "SendDelivery",
  "deliveryName": "Office Supplies",
  "deliveryAmount": 2500,
  "isPaid": true,
  "transactionId": "txn_abc123",
  "pickupAddress": "123 Main Street, Victoria Island, Lagos",
  "pickupLatLong": {
    "lat": 6.5244,
    "lon": 3.3792
  },
  "destinationAddress": "456 Business Avenue, Lekki, Lagos",
  "destinationLatLong": {
    "lat": 6.4654,
    "lon": 3.4064
  },
  "currentLocation": {
    "lat": 6.5100,
    "lon": 3.3850
  },
  "route": {
    "distance": 5200,
    "duration": 900,
    "geometry": "encoded_polyline_string"
  },
  "receiverPhoneNumber": "2348012345678",
  "senderPhoneNumber": "2348087654321",
  "additionalNotes": "Please call before delivery",
  "packageImage": [],
  "hasArrived": false,
  "scheduledTime": null,
  "pickedUpAt": "2025-01-15T10:30:00.000Z",
  "arrivedAtPickupLocationTime": "2025-01-15T10:15:00.000Z",
  "arrivedTime": null,
  "bulk": null,
  "order": null,
  "orderCode": null,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:45:00.000Z"
}