Delivery Fields Reference

Overview

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

Core Identifiers

string (UUID)

required

Unique identifier for the delivery

Used for API calls and internal references
Automatically generated on creation
Example: "abc123-def456-ghi789"

string

required

Human-readable tracking identifier

Shared with customers for tracking
12-character alphanumeric string
Example: "CHI-ABC123"

string (UUID)

required

ID of the user who created the delivery

Links to the API key owner
Used for authorization checks

string (UUID)

ID of the assigned driver

null if no driver assigned yet
Populated when driver accepts the delivery

Status & Type

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

enum

required

Type of delivery servicePossible values:

SendDelivery - Standard delivery from point A to B
RequestPickup - Pickup request service

string

Optional custom name for the delivery

Helps identify deliveries in your system
Example: "Office Supplies", "Customer Order #1234"

Location & Route

string

required

Full address of the pickup location

Human-readable format
Example: "123 Main Street, Victoria Island, Lagos"

object

required

Precise coordinates of the pickup location

Show properties

number

Latitude coordinateExample: 6.5244

number

Longitude coordinateExample: 3.3792

string

required

Full address of the delivery destination

Human-readable format
Example: "456 Business Avenue, Lekki, Lagos"

object

required

Precise coordinates of the destination

Show properties

number

Latitude coordinate

number

Longitude coordinate

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

Show properties

number

Current latitude

number

Current longitude

object

Calculated route information from pickup to destination

Show properties

number

Total distance in metersExample: 5200 (5.2 km)

number

Estimated duration in secondsExample: 900 (15 minutes)

string

Encoded polyline for map display

Use with mapping libraries to draw route
Google Polyline encoding format

Contact Information

string

required

Recipient’s phone number

Normalized to Nigerian format (234 prefix)
Example: "2348012345678"

string

required

Sender’s phone number

Normalized to Nigerian format (234 prefix)
Example: "2348087654321"

string

Special delivery instructions

Visible to the assigned driver
Example: "Please call before delivery", "Leave at gate"

Payment & Pricing

number

required

Total delivery cost in Naira (₦)

Includes all fees and charges
Example: 2500 (₦2,500)

boolean

required

Payment status

true if payment has been completed
false if payment is pending

string

Payment transaction reference

Links to the payment record
Populated after successful payment

Package Information

array

Photos of the package

Array of image objects
Uploaded by driver or sender
Used for proof of delivery

Timing & Schedule

datetime

Scheduled delivery time

ISO 8601 format
null for immediate deliveries
Example: "2025-01-15T14:00:00.000Z"

datetime

When the driver picked up the package

ISO 8601 format
null until package is picked up
Example: "2025-01-15T10:30:00.000Z"

datetime

When the driver arrived at the pickup location

ISO 8601 format
null until driver arrives
Example: "2025-01-15T10:15:00.000Z"

datetime

When the driver arrived at the destination

ISO 8601 format
null until driver arrives at destination
Example: "2025-01-15T11:00:00.000Z"

datetime

required

When the delivery was created

ISO 8601 format
Automatically set on creation
Example: "2025-01-15T10:00:00.000Z"

datetime

required

Last modification timestamp

ISO 8601 format
Updates automatically on any change
Example: "2025-01-15T10:45:00.000Z"

Driver Status

boolean

required

Whether the driver has arrived at the destination

Used for arrival notifications
true when driver reaches destination

Bulk Deliveries

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

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

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"
}

Overview

Pricing

Deliveries

Checkout

Payments

Webhooks

Real-time

Delivery Fields Reference

Overview

Core Identifiers

Status & Type

Location & Route

Contact Information

Payment & Pricing

Package Information

Timing & Schedule

Driver Status

Bulk Deliveries

Field Exclusions

Example Complete Delivery Object

​Overview

​Core Identifiers

​Status & Type

​Location & Route

​Contact Information

​Payment & Pricing

​Package Information

​Timing & Schedule

​Driver Status

​Bulk Deliveries

​Field Exclusions

​Example Complete Delivery Object

Overview

Core Identifiers

Status & Type

Location & Route

Contact Information

Payment & Pricing

Package Information

Timing & Schedule

Driver Status

Bulk Deliveries

Field Exclusions

Example Complete Delivery Object