API module

Base URLs:

Live: https://api.waysdrop.com
Staging: https://staging-api.waysdrop.com

Base path: /api This module is intended for third‑party integrations. All endpoints require the api-key header.

curl -X GET "https://api.waysdrop.com/api/countries?search=nigeria" \
  -H "api-key: wsp_live_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

Response shapes

Success

{
    "success": true,
    "message": "<human-readable message>",
    "data": {}
}

No content

Some endpoints return 204 No Content with an empty body.

Errors

Errors are returned using the global error envelope described in Errors.

Conventions

Decimals — Prisma Decimal fields serialize as strings in JSON (e.g. "1650.00", "2.00000").
Coordinates — Resolved locations use flat lat / lon numbers, not a nested loc object.
Optional fields — Geo/admin fields on resolved addresses vary by what was geocoded; omitted keys are not returned.

Origin and destination

Endpoints that accept origin and destination (POST /api/route, POST /api/pricing, POST /api/request) use the same address model. You can send a plain string, a minimal geocode object, or a full resolved object from your map picker.

Request input

Legacy string — geocoded server-side:

"origin": "Agege, Lagos, Nigeria"

Minimal object — preferred when you have coordinates or a place ID:

"origin": {
    "address": "Agege, Lagos, Nigeria",
    "lat": 6.617973099999999,
    "lon": 3.3208916,
    "googlePlaceId": "ChIJNSzoPHOROxARYADX4-24Io0"
}

Full object — pass the resolved shape from your map picker or a prior /api/route response. Extra geo/admin fields are preserved; geocoding uses address (or addressLine1), lat/lon, and googlePlaceId.

Input field	Type	Description
`address`	string (optional)	Free-text address for geocoding. Alias for `addressLine1` when pre-resolved
`lat` / `lon`	number (optional)	Coordinates from map picker — preferred over string geocoding
`googlePlaceId`	string (optional)	Google Place ID from map picker
`floor`	string (optional)	Floor or unit
`contactName`	string (optional)	Contact at this stop
`contactPhone`	string (optional)	E.164 phone at this stop
`contactEmail`	string (optional)	Email at this stop
`additionalNote`	string (optional)	Note for this stop (stored as `note`)
`id`	uuid (optional)	Saved address ID — skips geocoding when valid

On POST /api/request, origin contact fields can also be set at the top level (originContactName, originContactPhone, originContactEmail). Top-level destination contact fields are required unless already present on the destination object.

Resolved address object

After geocoding (in /api/route responses, delivery records, etc.), origin and destination resolve to this shape. All fields except country are optional — presence depends on the geocode result.

{
    "country": "Nigeria",
    "zipCode": "102212",
    "countryCode": "NG",
    "lat": 6.617973099999999,
    "lon": 3.3208916,
    "googlePlaceId": "ChIJNSzoPHOROxARYADX4-24Io0",
    "addressLine1": "Agege, Lagos, Nigeria",
    "addressLine2": "86 Oniwaya Rd, Agege, Lagos 102212, Lagos, Nigeria",
    "timezone": "Africa/Lagos",
    "regionName": "SW",
    "state": "Lagos",
    "lgaOrCity": "AGEGE",
    "region": "SW",
    "subregion": "Western Africa",
    "continentCode": "AF",
    "continentName": "Africa",
    "countryCodeAlpha3": "NGA",
    "adminUnitId": "NG-LAGOS-AGEGE",
    "adminUnitName": "AGEGE",
    "adminUnitType": "admin2",
    "adminUnitParentId": "NG-LAGOS",
    "admin1Id": "NG-LAGOS",
    "admin1Name": "Lagos",
    "admin2Id": "NG-LAGOS-AGEGE",
    "admin2Name": "AGEGE",
    "admin3Name": "Oniwaya/Papa-Uku",
    "operationalRegionId": "NG-SW",
    "h3Index": "8a5882643967fff",
    "phrase": "domeest.ponticello.sidewall",
    "resolution": 10,
    "centerLat": 6.617950538557496,
    "centerLon": 3.320709488840802,
    "contactName": "Raheem Kawojue",
    "contactPhone": "+2348131911964",
    "contactEmail": "[email protected]",
    "note": ""
}

Field groups

Group	Fields
Display	`addressLine1`, `addressLine2`, `floor`, `label`
Coordinates	`lat`, `lon`, `centerLat`, `centerLon`, `swLat`, `swLon`, `neLat`, `neLon`
Country / region	`country`, `countryCode`, `countryCodeAlpha3`, `state`, `lgaOrCity`, `zoneOrDistrict`, `region`, `regionName`, `regionalZone`, `subregion`, `zipCode`, `timezone`
Continent	`continentCode`, `continentName`
Admin hierarchy	`adminUnitId`, `adminUnitName`, `adminUnitType`, `adminUnitParentId`, `admin1Id`, `admin1Name`, `admin2Id`, `admin2Name`, `admin3Id`, `admin3Name`, `operationalRegionId`
Place reference	`googlePlaceId`
H3 grid	`h3Index`, `phrase`, `resolution`
Contact	`contactName`, `contactPhone`, `contactEmail`, `note`
Persisted only	`id`, `createdAt`, `updatedAt`, `deletedAt` — present on stored delivery addresses

Persisted addresses on deliveries (GET /api/deliveries/:deliveryId, POST /api/request → delivery.origin / delivery.destination) include id and timestamps in addition to the fields above.

Endpoints

GET /api/countries

Fetch available countries for routing and pricing. Query

search (optional, string)

200 Response

{
    "success": true,
    "message": "Countries fetched successfully",
    "data": [
        {
            "value": "NG",
            "name": "Nigeria",
            "type": "INTER_COUNTRY",
            "country": "Nigeria",
            "countryCode": "NG",
            "countryCodeAlpha3": "NGA",
            "continentCode": "AF",
            "continentName": "Africa",
            "lat": 9.082,
            "lon": 8.6753
        }
    ]
}

Response fields

Field	Description
`value`	ISO country code (e.g. `"NG"`)
`name`	Country display name
`type`	Always `"INTER_COUNTRY"`
`country` / `countryCode`	Country name and ISO code
`countryCodeAlpha3`	ISO 3166-1 alpha-3 code
`continentCode` / `continentName`	Continent metadata
`lat` / `lon`	Country centroid coordinates (when available)

Without search, returns up to 50 results.

GET /api/states

Fetch available states. Query

search (optional, string)

200 Response

{
    "success": true,
    "message": "States fetched successfully",
    "data": [
        {
            "value": "ng-admin1-lagos",
            "name": "Lagos",
            "type": "INTER_STATE",
            "state": "Lagos",
            "country": "Nigeria",
            "countryCode": "NG",
            "continentCode": "AF",
            "continentName": "Africa",
            "regionalZone": "South West",
            "admin1Id": "ng-admin1-lagos",
            "admin1Name": "Lagos",
            "lat": 6.5244,
            "lon": 3.3792
        }
    ]
}

Response fields

Field	Description
`value`	State route identifier
`name`	State display name
`type`	Always `"INTER_STATE"`
`state`	State name
`regionalZone`	Broad regional grouping
`admin1Id` / `admin1Name`	Admin-1 hierarchy identifiers

GET /api/cities

Fetch available cities. Query

search (optional, string)

200 Response

{
    "success": true,
    "message": "Cities fetched successfully",
    "data": [
        {
            "value": "ChIJ.....",
            "locationId": "ng-lagos-ikeja",
            "googlePlaceId": "ChIJ.....",
            "country": "Nigeria",
            "countryCode": "NG",
            "countryCodeAlpha3": "NGA",
            "lat": 6.6018,
            "lon": 3.3515,
            "lgaOrCity": "Ikeja",
            "state": "Lagos",
            "zoneOrDistrict": "Ikeja",
            "region": "SW",
            "regionName": "South West",
            "regionalZone": "South West",
            "adminUnitName": "Ikeja"
        }
    ]
}

Response notes

value is googlePlaceId when available, otherwise locationId.
lat / lon are the coordinates used for distance and ETA calculations.
Without search, returns up to 50 results.

POST /api/route

Get route data between two addresses. Body

{
    "origin": {
        "address": "Ladipo Kuku Street, Ikeja Lagos",
        "lat": 6.6018,
        "lon": 3.3515
    },
    "destination": "Adewole Estate, Surulere Lagos"
}

200 Response

{
    "success": true,
    "message": "Route data fetched successfully",
    "data": {
        "distance": { "distanceKm": 12.743, "etaSeconds": 1649 },
        "routeType": "INTER_CITY",
        "origin": {
            "country": "Nigeria",
            "zipCode": "102212",
            "countryCode": "NG",
            "lat": 6.617973099999999,
            "lon": 3.3208916,
            "googlePlaceId": "ChIJNSzoPHOROxARYADX4-24Io0",
            "addressLine1": "Agege, Lagos, Nigeria",
            "addressLine2": "86 Oniwaya Rd, Agege, Lagos 102212, Lagos, Nigeria",
            "timezone": "Africa/Lagos",
            "regionName": "SW",
            "state": "Lagos",
            "lgaOrCity": "AGEGE",
            "region": "SW",
            "subregion": "Western Africa",
            "continentCode": "AF",
            "continentName": "Africa",
            "countryCodeAlpha3": "NGA",
            "adminUnitId": "NG-LAGOS-AGEGE",
            "adminUnitName": "AGEGE",
            "adminUnitType": "admin2",
            "adminUnitParentId": "NG-LAGOS",
            "admin1Id": "NG-LAGOS",
            "admin1Name": "Lagos",
            "admin2Id": "NG-LAGOS-AGEGE",
            "admin2Name": "AGEGE",
            "admin3Name": "Oniwaya/Papa-Uku",
            "operationalRegionId": "NG-SW",
            "h3Index": "8a5882643967fff",
            "phrase": "domeest.ponticello.sidewall",
            "resolution": 10,
            "centerLat": 6.617950538557496,
            "centerLon": 3.320709488840802
        },
        "destination": {
            "country": "Nigeria",
            "zipCode": "102212",
            "countryCode": "NG",
            "lat": 6.5244,
            "lon": 3.3792,
            "googlePlaceId": "ChIJ6cPolh-QOxAR_rCHmFNKObg",
            "addressLine1": "Gbagada, Lagos, Nigeria",
            "addressLine2": "Gbagada, Lagos, Nigeria",
            "timezone": "Africa/Lagos",
            "regionName": "SW",
            "state": "Lagos",
            "lgaOrCity": "GBAGADA",
            "region": "SW",
            "subregion": "Western Africa",
            "continentCode": "AF",
            "continentName": "Africa",
            "countryCodeAlpha3": "NGA",
            "admin1Id": "NG-LAGOS",
            "admin1Name": "Lagos",
            "operationalRegionId": "NG-SW"
        }
    }
}

Response notes

origin and destination use the resolved address object shape. Contact fields are not included unless you sent them on input.
routeType is one of INTER_CITY, INTER_STATE, INTER_REGION, INTER_COUNTRY, or INTER_CONTINENT.
distance.distanceKm and distance.etaSeconds use the max of line and road distance for safety.

GET /api/fleet-types

Fetch available fleet types. 200 Response

{
    "success": true,
    "message": "Fleet types fetched successfully",
    "data": [
        {
            "id": "uuid",
            "name": "Bike",
            "icon": "https://cdn.waysdrop.com/fleets/bike.png",
            "description": "Small packages"
        }
    ]
}

Only active fleet types are returned. icon and description may be null.

POST /api/pricing

Get pricing for a delivery request. Two pricing modes are supported — use one or the other. Mode A — by package IDs (preferred) Resolves weight and value from your saved packages. Matches the pricing logic used by POST /api/request. Requires an authenticated user (API key owner).

{
    "origin": "Ladipo Kuku Street, Ikeja Lagos",
    "destination": "Adewole Estate, Surulere Lagos",
    "packagesId": ["uuid-1", "uuid-2"],
    "urgencyType": "PRIORITY",
    "fleetTypeId": "uuid",
    "courierSelection": "ANYONE",
    "deliveryFeePayer": "CREATOR"
}

Mode B — by weight and value Provide totals directly when you do not have saved packages.

{
    "origin": "Ladipo Kuku Street, Ikeja Lagos",
    "destination": "Adewole Estate, Surulere Lagos",
    "totalWeight": 100,
    "totalValue": 1000,
    "urgencyType": "PRIORITY",
    "fleetTypeId": "uuid",
    "courierSelection": "ANYONE"
}

Body fields

Field	Type	Required	Description
`origin`	string \| object	Yes	Pickup address (see Origin and destination)
`destination`	string \| object	Yes	Drop-off address
`packagesId`	string[]	Mode A	Package UUIDs — preferred; resolves weight/value automatically
`totalWeight`	number	Mode B	Total weight in kg. Required when `packagesId` is omitted
`totalValue`	number	Mode B	Total value in NGN. Required when `packagesId` is omitted
`urgencyType`	enum	No	`PRIORITY`, `STANDARD`, or `SCHEDULED`
`deliveryDate`	string	SCHEDULED	Date in `YYYY-MM-DD` format
`deliverySlot`	string	SCHEDULED	Time window, e.g. `04:00 - 14:00`
`slot`	string	SCHEDULED	Alias for `deliverySlot`
`fleetTypeId`	uuid	No	Fleet type override. If incompatible with weight, the first compatible type is used
`courierSelection`	enum	No	`ANYONE` (default) or `SPECIFIC`
`courierId`	uuid	SPECIFIC	Courier profile ID when `courierSelection` is `SPECIFIC`
`courierProfileId`	uuid	No	Alias for `courierId`
`deliveryFeePayer`	enum	No	`CREATOR` (default), `RECIPIENT`, or `SPLIT`. Who pays the delivery fee

Mode A response — `packagesId`

200 Response

{
    "success": true,
    "message": "Pricing fetched successfully",
    "data": {
        "deliveryCost": {
            "distance": { "distanceKm": 12.743, "etaSeconds": 1649 },
            "routeType": "INTER_CITY",
            "tierIds": {
                "countryPricingId": "uuid",
                "statePricingId": "uuid",
                "cityPricingId": "uuid"
            },
            "costs": {
                "base": "1200.00",
                "fleet": "100.00",
                "deliverySubtotal": "1550.00",
                "total": "1700.00",
                "weight": "150.00",
                "insurance": "0.00",
                "surcharge": "100.00",
                "serviceFee": "150.00"
            },
            "breakdown": {
                "baseCharge": "Base distance charge for 12.74km",
                "weightCharge": "Additional charge for 9kg",
                "insuranceCharge": null,
                "fleetCharge": "Fleet charge for Bike delivery",
                "surchargeCharge": "Surcharge for PRIORITY:PRIORITY",
                "serviceFeeCharge": "Service fee (flat) → 150.00"
            },
            "courierPricingRule": null,
            "totalWeight": 9,
            "totalValue": 250000
        },
        "promotion": null,
        "deliveryFee": {
            "payer": "CREATOR",
            "gross": {
                "delivery": "1550.00",
                "serviceFee": "150.00",
                "hubCommission": "0.00",
                "bundledTotal": "1700.00"
            },
            "creator": {
                "amount": "1700.00",
                "paymentRequired": true,
                "paid": false
            },
            "recipient": {
                "amount": "0.00",
                "paymentRequired": false,
                "paid": false,
                "checkoutUrl": null
            },
            "promotion": {
                "settlementMode": null,
                "platformFunded": false,
                "settledAmount": "0.00",
                "discountAmount": "0.00",
                "isApplied": false
            }
        },
        "matchingEligible": true,
        "payOnDelivery": {
            "enabled": false,
            "collectAmount": "250000.00",
            "collectTarget": "PACKAGE_VALUE"
        }
    }
}

Mode A response notes

costs.total = deliverySubtotal + serviceFee (+ hub commission when applicable).
deliveryFee describes who pays what before a request is created.
matchingEligible is true when courier matching can start immediately after payment.
When courierSelection is SPECIFIC, a courier object may also be included.
Auto-promotions are not applied on this endpoint.

Mode B response — `totalWeight` + `totalValue`

200 Response

{
    "success": true,
    "message": "Pricing fetched successfully",
    "data": {
        "distance": { "distanceKm": 12.743, "etaSeconds": 1649 },
        "routeType": "INTER_CITY",
        "tierIds": {
            "countryPricingId": "uuid",
            "statePricingId": "uuid",
            "cityPricingId": "uuid"
        },
        "costs": {
            "base": "1200.00",
            "fleet": "100.00",
            "deliverySubtotal": "1550.00",
            "total": "1700.00",
            "weight": "150.00",
            "insurance": "0.00",
            "surcharge": "100.00",
            "serviceFee": "150.00"
        },
        "breakdown": {
            "baseCharge": "Base distance charge for 12.74km",
            "weightCharge": "Additional charge for 100kg",
            "insuranceCharge": null,
            "fleetCharge": "Fleet charge for Bike delivery",
            "surchargeCharge": "Surcharge for PRIORITY:PRIORITY",
            "serviceFeeCharge": "Service fee (flat) → 150.00"
        },
        "courierPricingRule": null
    }
}

When a specific courier has a matching pricing rule, courierPricingRule is populated and weight/fleet/surcharge may be zeroed:

"courierPricingRule": {
    "id": "uuid",
    "capBy": "LOCATION",
    "from": "Lagos",
    "to": "Ibadan",
    "withinKmRadius": null,
    "isPerKg": false
}

Common errors

400 Provide packagesId or both totalWeight and totalValue
400 Authenticated user is required when pricing by packagesId

POST /api/request

Create a delivery request (P2P). Body

{
    "origin": {
        "country": "Nigeria",
        "zipCode": "102212",
        "countryCode": "NG",
        "lat": 6.617973099999999,
        "lon": 3.3208916,
        "googlePlaceId": "ChIJNSzoPHOROxARYADX4-24Io0",
        "addressLine1": "Agege, Lagos, Nigeria",
        "addressLine2": "86 Oniwaya Rd, Agege, Lagos 102212, Lagos, Nigeria",
        "contactName": "Raheem Kawojue",
        "contactPhone": "+2348131911964",
        "contactEmail": "[email protected]"
    },
    "destination": {
        "country": "Nigeria",
        "countryCode": "NG",
        "lat": 6.5244,
        "lon": 3.3792,
        "googlePlaceId": "ChIJ6cPolh-QOxAR_rCHmFNKObg",
        "addressLine1": "Gbagada, Lagos, Nigeria",
        "contactName": "Jane Recipient",
        "contactPhone": "+2348098765432",
        "contactEmail": "[email protected]"
    },
    "packagesId": ["uuid-1", "uuid-2"],
    "type": "PICKUP",
    "courierSelection": "ANYONE",
    "urgencyType": "PRIORITY",
    "deliveryDate": "2026-01-24",
    "deliverySlot": "04:00 - 14:00",
    "fleetTypeId": "uuid",
    "requireCollectionProofCode": true,
    "requireDeliveryProofCode": true,
    "deliveryFeePayer": "CREATOR",
    "payOnDelivery": false,
    "paymentMethodType": "WALLET",
    "link3rdPartyByContactInfo": true,
    "note": "Any additional notes"
}

When using the full object from your map picker, contact fields on origin / destination satisfy contact requirements — top-level originContact* / destinationContact* fields are optional in that case. Body fields

Field	Type	Required	Description
`origin`	string \| object	Yes	Pickup address (see Origin and destination)
`destination`	string \| object	Yes	Drop-off address
`originContactEmail`	string	No	Defaults to your account email if omitted
`originContactPhone`	string	No	Defaults to your account phone if omitted
`originContactName`	string	No	Defaults to your account name if omitted
`destinationContactEmail`	string	Yes	Recipient email
`destinationContactPhone`	string	Yes	Recipient phone (E.164)
`destinationContactName`	string	Yes	Recipient name
`note`	string	No	Delivery notes (max 128 chars)
`link3rdPartyByContactInfo`	boolean	No	Default `false`. If `true`, notifies the recipient on the Waysdrop app and links the delivery to their account when contact info matches
`notify3rdParty`	boolean	No	Alias for `link3rdPartyByContactInfo`
`packagesId`	string[]	Yes	Package UUIDs to deliver
`type`	enum	Yes	`PICKUP` or `DROP_OFF`
`urgencyType`	enum	No	`PRIORITY`, `STANDARD`, or `SCHEDULED`
`deliveryDate`	string	SCHEDULED	Required when `urgencyType` is `SCHEDULED`
`deliverySlot`	string	SCHEDULED	Time window, e.g. `04:00 - 14:00`
`fleetTypeId`	uuid	No	Fleet type override
`requireCollectionProofCode`	boolean	No	Default `true`. Sends a collection proof code to origin contact
`requireDeliveryProofCode`	boolean	No	Default `true`. Ignored when `payOnDelivery` is `true` (POD uses its own proof flow)
`deliveryFeePayer`	enum	No	Default `CREATOR`. `CREATOR` debits Merchant Wallet; `RECIPIENT` or `SPLIT` for other arrangements
`payOnDelivery`	boolean	No	Default `false`. Enable pay-on-delivery collection
`podRemitTo`	enum	POD	Required when `payOnDelivery` is `true`. `MY_WALLET` (default) or `COURIER_WALLET`
`podCourierProfileId`	uuid	POD	Required when `podRemitTo` is `COURIER_WALLET`
`paymentMethodType`	enum	No	Default `WALLET`. `WALLET` or `CHECKOUT`
`courierSelection`	enum	Yes	`ANYONE`, `SPECIFIC`, or `MERCHANT_SPECIAL_COURIERS`
`courierId`	uuid	SPECIFIC	Required when `courierSelection` is `SPECIFIC`

Courier selection

ANYONE — any available courier on the platform
SPECIFIC — assign a courier you already have in the system (courierId required)
MERCHANT_SPECIAL_COURIERS — assign from your merchant-specific courier list (requires couriers added in the merchant dashboard)

Response — `paymentMethodType: WALLET` (default)

201 Response

{
    "success": true,
    "message": "Delivery request created successfully",
    "data": {
        "id": "uuid",
        "deliveryId": "uuid",
        "userId": "uuid",
        "profileId": "uuid",
        "type": "PICKUP",
        "status": "PENDING",
        "totalWeight": "9.00000",
        "totalValue": "250000.00",
        "createdAt": "2026-01-24T12:34:56.789Z",
        "updatedAt": "2026-01-24T12:34:56.789Z",
        "deletedAt": null,
        "delivery": {
            "id": "uuid",
            "userId": "uuid",
            "trackingId": "P2P-XXXXX",
            "type": "P2P",
            "status": "REQUEST_CREATED",
            "routeType": "INTER_CITY",
            "fleetTypeId": "uuid",
            "apiKeyId": "uuid",
            "distanceKm": 12.743,
            "etaSeconds": 1649,
            "deliveryFee": "1550.00",
            "deliveryFeeTotal": "1550.00",
            "serviceFee": "150.00",
            "weightFee": "150.00",
            "fleetFee": "100.00",
            "surchargeFee": "100.00",
            "insuranceFee": "0.00",
            "baseOrDistanceFee": "1200.00",
            "deliveryFeePayer": "CREATOR",
            "courierMatching": "ANYONE",
            "origin": {
                "id": "uuid",
                "country": "Nigeria",
                "zipCode": "102212",
                "countryCode": "NG",
                "lat": 6.617973099999999,
                "lon": 3.3208916,
                "googlePlaceId": "ChIJNSzoPHOROxARYADX4-24Io0",
                "addressLine1": "Agege, Lagos, Nigeria",
                "addressLine2": "86 Oniwaya Rd, Agege, Lagos 102212, Lagos, Nigeria",
                "timezone": "Africa/Lagos",
                "regionName": "SW",
                "state": "Lagos",
                "lgaOrCity": "AGEGE",
                "region": "SW",
                "subregion": "Western Africa",
                "continentCode": "AF",
                "continentName": "Africa",
                "countryCodeAlpha3": "NGA",
                "adminUnitId": "NG-LAGOS-AGEGE",
                "adminUnitName": "AGEGE",
                "adminUnitType": "admin2",
                "adminUnitParentId": "NG-LAGOS",
                "admin1Id": "NG-LAGOS",
                "admin1Name": "Lagos",
                "admin2Id": "NG-LAGOS-AGEGE",
                "admin2Name": "AGEGE",
                "admin3Name": "Oniwaya/Papa-Uku",
                "operationalRegionId": "NG-SW",
                "h3Index": "8a5882643967fff",
                "phrase": "domeest.ponticello.sidewall",
                "resolution": 10,
                "centerLat": 6.617950538557496,
                "centerLon": 3.320709488840802,
                "contactName": "Raheem Kawojue",
                "contactPhone": "+2348131911964",
                "contactEmail": "[email protected]",
                "note": "",
                "createdAt": "2026-01-24T12:34:56.789Z",
                "updatedAt": "2026-01-24T12:34:56.789Z"
            },
            "destination": {
                "id": "uuid",
                "country": "Nigeria",
                "zipCode": "102212",
                "countryCode": "NG",
                "lat": 6.5244,
                "lon": 3.3792,
                "googlePlaceId": "ChIJ6cPolh-QOxAR_rCHmFNKObg",
                "addressLine1": "Gbagada, Lagos, Nigeria",
                "addressLine2": "Gbagada, Lagos, Nigeria",
                "timezone": "Africa/Lagos",
                "regionName": "SW",
                "state": "Lagos",
                "lgaOrCity": "GBAGADA",
                "region": "SW",
                "subregion": "Western Africa",
                "continentCode": "AF",
                "continentName": "Africa",
                "countryCodeAlpha3": "NGA",
                "admin1Id": "NG-LAGOS",
                "admin1Name": "Lagos",
                "operationalRegionId": "NG-SW",
                "contactName": "Jane Recipient",
                "contactPhone": "+2348098765432",
                "contactEmail": "[email protected]",
                "note": "",
                "createdAt": "2026-01-24T12:34:56.789Z",
                "updatedAt": "2026-01-24T12:34:56.789Z"
            }
        },
        "deliveryFee": {
            "payer": "CREATOR",
            "gross": {
                "delivery": "1550.00",
                "serviceFee": "150.00",
                "hubCommission": "0.00",
                "bundledTotal": "1700.00"
            },
            "creator": {
                "amount": "1700.00",
                "paymentRequired": true,
                "paid": true
            },
            "recipient": {
                "amount": "0.00",
                "paymentRequired": false,
                "paid": false,
                "checkoutUrl": null
            },
            "promotion": {
                "settlementMode": null,
                "platformFunded": false,
                "settledAmount": "0.00",
                "discountAmount": "0.00",
                "isApplied": false
            }
        },
        "matchingEligible": true
    }
}

Response — `paymentMethodType: CHECKOUT`

Returns a Paystack checkout payload instead of debiting the wallet immediately:

{
    "success": true,
    "message": "Delivery request created successfully",
    "data": {
        "status": true,
        "message": "Authorization URL created",
        "data": {
            "authorization_url": "https://checkout.paystack.com/...",
            "access_code": "...",
            "reference": "..."
        },
        "deliveryFee": { "...": "..." },
        "matchingEligible": false
    }
}

Courier matching starts after payment succeeds.

Response — `payOnDelivery: true`

Adds a payOnDelivery block:

"payOnDelivery": {
    "enabled": true,
    "collectAmount": "250000.00",
    "collectTarget": "PACKAGE_VALUE",
    "remitTo": "MY_WALLET"
}

Response notes

totalWeight and totalValue on the P2P record are strings (Decimal).
delivery.distanceKm is a number (float).
delivery.status is always REQUEST_CREATED on create; status on the P2P record reflects payment state (PENDING, PENDING_PAYMENT, etc.).
Full origin / destination use the resolved address object plus id and timestamps.

Common errors

422 Insufficient balance
400 Invalid packages selection
400 Origin and destination cannot be the same
404 Fleet type not found
404 No merchant specific couriers found (when using MERCHANT_SPECIAL_COURIERS without configured couriers)

POST /api/request/:deliveryId/cancel

Cancel an eligible delivery request. Path params

deliveryId (uuid)

201 Response

{
    "success": true,
    "message": "Delivery request has been canceled",
    "data": {
        "delivery": { "id": "uuid" }
    }
}

Common errors

404 Delivery request not found
400 Delivery request can not be canceled due to its current status
400 You can only cancel a delivery request twice every 3 hours

POST /api/package

Create or edit a package. Body Use this endpoint to create a new package or update an existing one.

To create, omit packageId and provide all required fields.
To update, include packageId and provide only the fields you want to change.

Create example

{
    "packageType": "Electronics",
    "image": "https://cdn.waysdrop.com/packages/laptop.jpg",
    "name": "Laptop",
    "description": "Package description",
    "quantity": 1,
    "size": "SMALL",
    "value": 250000
}

Update example

{
    "packageId": "uuid",
    "description": "Updated description"
}

Fields

Field	Type	Required on create	Description
`packageId`	uuid	No	Include to update an existing package
`packageType`	string	Yes	Category label
`image`	url	No	Must be hosted on `cdn.waysdrop.com`
`name`	string	Yes	Package name
`description`	string	No	Max 128 chars
`quantity`	int	Yes	Number of items
`size`	enum	Yes	`SMALL` (≈2 kg), `MEDIUM` (≈7 kg), or `LARGE` (≈15 kg)
`value`	number	Yes	Total value in NGN

Weight is derived from size on create — you do not send weight directly. 201 Response

{
    "success": true,
    "message": "Package saved successfully",
    "data": {
        "id": "uuid",
        "userId": "uuid",
        "p2pDeliveryId": null,
        "errandDeliveryId": null,
        "errandStoreId": null,
        "productId": null,
        "variantCombinationId": null,
        "packageType": "Electronics",
        "name": "Laptop",
        "image": "https://cdn.waysdrop.com/....jpg",
        "description": "Package description",
        "quantity": 1,
        "weight": "2.00000",
        "value": "250000.00",
        "size": "SMALL",
        "type": "PACKAGE_ITEM",
        "selectedOptions": [],
        "createdAt": "2026-01-24T12:34:56.789Z",
        "updatedAt": "2026-01-24T12:34:56.789Z",
        "deletedAt": null
    }
}

DELETE /api/package/:packageId

Delete a package. Path params

packageId (uuid)

204 Response

No content

GET /api/packages

Get packages that have not been assigned to a delivery (for the authenticated user). 200 Response

{
    "success": true,
    "message": "Packages retrieved successfully",
    "data": [
        {
            "id": "uuid",
            "userId": "uuid",
            "p2pDeliveryId": null,
            "packageType": "Electronics",
            "name": "Laptop",
            "image": "https://cdn.waysdrop.com/....jpg",
            "description": "Package description",
            "quantity": 1,
            "weight": "2.00000",
            "value": "250000.00",
            "size": "SMALL",
            "type": "PACKAGE_ITEM",
            "selectedOptions": [],
            "createdAt": "2026-01-24T12:34:56.789Z",
            "updatedAt": "2026-01-24T12:34:56.789Z",
            "deletedAt": null
        }
    ]
}

Returns the full DeliveryPackage record for each unassigned package.

GET /api/deliveries/:deliveryId

Get a delivery (for the authenticated user). Path params

deliveryId (uuid)

200 Response

{
    "success": true,
    "message": "Delivery retrieved successfully",
    "data": {
        "id": "uuid",
        "userId": "uuid",
        "trackingId": "P2P-XXXXX",
        "type": "P2P",
        "status": "IN_TRANSIT",
        "routeType": "INTER_CITY",
        "distanceKm": 12.743,
        "etaSeconds": 1649,
        "deliveryFee": "1550.00",
        "deliveryFeeTotal": "1550.00",
        "serviceFee": "150.00",
        "weightFee": "150.00",
        "fleetFee": "100.00",
        "surchargeFee": "100.00",
        "insuranceFee": "0.00",
        "baseOrDistanceFee": "1200.00",
        "deliveryFeePayer": "CREATOR",
        "courierMatching": "ANYONE",
        "requireCollectionProofCode": true,
        "requireDeliveryProofCode": true,
        "link3rdPartyByContactInfo": true,
        "urgencyType": "PRIORITY",
        "deliveryDate": "2026-01-24T00:00:00.000Z",
        "deliverySlot": "04:00 - 14:00",
        "fleetTypeId": "uuid",
        "createdAt": "2026-01-24T12:34:56.789Z",
        "updatedAt": "2026-01-24T12:40:00.000Z",
        "fleetType": {
            "id": "uuid",
            "name": "Bike",
            "icon": "https://cdn.waysdrop.com/..."
        },
        "p2pDelivery": {
            "id": "uuid",
            "deliveryId": "uuid",
            "userId": "uuid",
            "profileId": "uuid",
            "type": "PICKUP",
            "status": "PENDING",
            "totalWeight": "9.00000",
            "totalValue": "250000.00",
            "createdAt": "2026-01-24T12:34:56.789Z",
            "updatedAt": "2026-01-24T12:34:56.789Z"
        },
        "origin": {
            "id": "uuid",
            "country": "Nigeria",
            "zipCode": "102212",
            "countryCode": "NG",
            "lat": 6.617973099999999,
            "lon": 3.3208916,
            "googlePlaceId": "ChIJNSzoPHOROxARYADX4-24Io0",
            "addressLine1": "Agege, Lagos, Nigeria",
            "addressLine2": "86 Oniwaya Rd, Agege, Lagos 102212, Lagos, Nigeria",
            "timezone": "Africa/Lagos",
            "regionName": "SW",
            "state": "Lagos",
            "lgaOrCity": "AGEGE",
            "region": "SW",
            "subregion": "Western Africa",
            "continentCode": "AF",
            "continentName": "Africa",
            "countryCodeAlpha3": "NGA",
            "adminUnitId": "NG-LAGOS-AGEGE",
            "adminUnitName": "AGEGE",
            "adminUnitType": "admin2",
            "adminUnitParentId": "NG-LAGOS",
            "admin1Id": "NG-LAGOS",
            "admin1Name": "Lagos",
            "admin2Id": "NG-LAGOS-AGEGE",
            "admin2Name": "AGEGE",
            "admin3Name": "Oniwaya/Papa-Uku",
            "operationalRegionId": "NG-SW",
            "h3Index": "8a5882643967fff",
            "phrase": "domeest.ponticello.sidewall",
            "resolution": 10,
            "centerLat": 6.617950538557496,
            "centerLon": 3.320709488840802,
            "contactName": "Raheem Kawojue",
            "contactPhone": "+2348131911964",
            "contactEmail": "[email protected]",
            "note": "",
            "createdAt": "2026-01-24T12:34:56.789Z",
            "updatedAt": "2026-01-24T12:34:56.789Z"
        },
        "destination": {
            "id": "uuid",
            "country": "Nigeria",
            "zipCode": "102212",
            "countryCode": "NG",
            "lat": 6.5244,
            "lon": 3.3792,
            "googlePlaceId": "ChIJ6cPolh-QOxAR_rCHmFNKObg",
            "addressLine1": "Gbagada, Lagos, Nigeria",
            "addressLine2": "Gbagada, Lagos, Nigeria",
            "timezone": "Africa/Lagos",
            "regionName": "SW",
            "state": "Lagos",
            "lgaOrCity": "GBAGADA",
            "region": "SW",
            "subregion": "Western Africa",
            "continentCode": "AF",
            "continentName": "Africa",
            "countryCodeAlpha3": "NGA",
            "admin1Id": "NG-LAGOS",
            "admin1Name": "Lagos",
            "operationalRegionId": "NG-SW",
            "contactName": "Jane Recipient",
            "contactPhone": "+2348098765432",
            "contactEmail": "[email protected]",
            "note": "",
            "createdAt": "2026-01-24T12:34:56.789Z",
            "updatedAt": "2026-01-24T12:34:56.789Z"
        },
        "proofs": [
            {
                "id": "uuid",
                "type": "COLLECTION",
                "code": null,
                "isActive": false,
                "scannedAt": null,
                "createdAt": "2026-01-24T12:34:56.789Z"
            }
        ],
        "deliverySteps": [
            {
                "id": "uuid",
                "step": "REQUEST_CREATED",
                "active": false,
                "updatedAt": "2026-01-24T12:34:56.789Z"
            },
            {
                "id": "uuid",
                "step": "IN_TRANSIT",
                "active": true,
                "updatedAt": "2026-01-24T12:40:00.000Z"
            }
        ],
        "courier": {
            "name": "Courier name",
            "phone": "+2348012345678",
            "profilePhoto": "https://cdn.waysdrop.com/....jpg",
            "currentLocation": {
                "country": "Nigeria",
                "state": "Lagos",
                "lgaOrCity": "Ikeja",
                "lat": 6.6018,
                "lon": 3.3515
            },
            "eta": {
                "from": "2026-01-24T12:50:00.000Z",
                "to": "2026-01-24T13:30:00.000Z"
            },
            "fleet": {
                "regNo": "ABC-123",
                "make": "Honda",
                "model": "CBR",
                "colour": "Red",
                "typeId": "uuid"
            }
        }
    }
}

Response notes

The delivery object includes all scalar Delivery fields — the example shows the most useful ones.
origin and destination use the full resolved address object with id and timestamps.
courier is omitted (not null) until a courier is assigned.
currentLocation uses flat lat / lon, not a nested loc object.
Proof code is null until the proof has been scanned (scannedAt is set).
deliverySteps only includes visible steps (hidden steps are excluded).
p2pDelivery.totalWeight and totalValue are strings (Decimal).

Get started

API reference

Api

API module

Response shapes

Success

No content

Errors

Conventions

Origin and destination

Request input

Resolved address object

Endpoints

GET /api/countries

GET /api/states

GET /api/cities

POST /api/route

GET /api/fleet-types

POST /api/pricing

Mode A response — `packagesId`

Mode B response — `totalWeight` + `totalValue`

POST /api/request

Response — `paymentMethodType: WALLET` (default)

Response — `paymentMethodType: CHECKOUT`

Response — `payOnDelivery: true`

POST /api/request/:deliveryId/cancel

POST /api/package

DELETE /api/package/:packageId

GET /api/packages

GET /api/deliveries/:deliveryId

​API module

​Response shapes

​Success

​No content

​Errors

​Conventions

​Origin and destination

​Request input

​Resolved address object

​Endpoints

​GET /api/countries

​GET /api/states

​GET /api/cities

​POST /api/route

​GET /api/fleet-types

​POST /api/pricing

​Mode A response — packagesId

​Mode B response — totalWeight + totalValue

​POST /api/request

​Response — paymentMethodType: WALLET (default)

​Response — paymentMethodType: CHECKOUT

​Response — payOnDelivery: true

​POST /api/request/:deliveryId/cancel

​POST /api/package

​DELETE /api/package/:packageId

​GET /api/packages

​GET /api/deliveries/:deliveryId

API module

Response shapes

Success

No content

Errors

Conventions

Origin and destination

Request input

Resolved address object

Endpoints

GET /api/countries

GET /api/states

GET /api/cities

POST /api/route

GET /api/fleet-types

POST /api/pricing

Mode A response — `packagesId`

Mode B response — `totalWeight` + `totalValue`

POST /api/request

Response — `paymentMethodType: WALLET` (default)

Response — `paymentMethodType: CHECKOUT`

Response — `payOnDelivery: true`

POST /api/request/:deliveryId/cancel

POST /api/package

DELETE /api/package/:packageId

GET /api/packages

GET /api/deliveries/:deliveryId