Shipments & Bookings

Book parcel deliveries, lock rates via rate_tokens, reserve escrow balances, and track delivery progress.

POST

Create a new shipment booking. Automatically reserves the required fare in the merchant escrow ledger, locks pricing using the rate_token if provided, creates a tracking identifier, and broadcasts order dispatch to eligible carrier fleets or marketplace riders.

Authentication: Secret Key / JWT

Request Body Fields

Field	Type	Requirement	Description
customer_name	string	Required	Full legal name of parcel recipient.
customer_phone	string	Required	Recipient phone number (+234...).
pickup_address	string	Required	Full street address for parcel pickup.
pickup_latitude	decimal	Required	Geocoded pickup latitude.
pickup_longitude	decimal	Required	Geocoded pickup longitude.
dropoff_address	string	Required	Full street address for destination dropoff.
dropoff_latitude	decimal	Required	Geocoded dropoff latitude.
dropoff_longitude	decimal	Required	Geocoded dropoff longitude.
declared_value	decimal	Required	Package declared value in local currency. Mandatory for insurance and security deposit gating.
package_weight_kg	decimal	Optional	Actual parcel weight in kilograms. Default: `0.00`
rate_token	string	Optional	Cryptographic rate token obtained from POST /rates/. Locks in verified service level, mode, and fare.
fulfillment_mode	string	Optional	Delivery routing mode. Allowed:`"marketplace""carrier"` Default: `marketplace`
service_level	string	Optional	Delivery velocity service level. Allowed:`"EXPRESS""STANDARD""SAME_DAY""SAVER"` Default: `STANDARD`
merchant_reference	string	Optional	Merchant internal order or tracking reference string.
pickup_country	string	Optional	Two-letter ISO country code for pickup location. Default: `NG`
dropoff_country	string	Optional	Two-letter ISO country code for dropoff (must match pickup country). Default: `NG`
webhook_url	string	Optional	Optional per-shipment HTTPS webhook callback URL for state transitions.
package_description	string	Optional	Item description for driver and customs handling.

Request ExampleHTTPS Live Endpoint

curl -X POST https://api.tumr.app/api/v1/shipments/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "ORDER-98421",
    "customer_name": "Ada Okafor",
    "customer_phone": "+2348012345678",
    "pickup_address": "12 Admiralty Way, Lekki Phase 1, Lagos",
    "pickup_latitude": 6.4281,
    "pickup_longitude": 3.4219,
    "dropoff_address": "45 Allen Avenue, Ikeja, Lagos",
    "dropoff_latitude": 6.5244,
    "dropoff_longitude": 3.3792,
    "package_weight_kg": 2.5,
    "declared_value": 15000.00,
    "pickup_country": "NG",
    "rate_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "package_description": "Electronics (Headphones)"
  }'

Response Payload

201 Created

application/json

{
  "id": "76495b28-1004-4b52-9fe1-d64e8e5ab190",
  "tracking_number": "AKR-83491054",
  "merchant_reference": "ORDER-98421",
  "status": "PENDING",
  "customer_name": "Ada Okafor",
  "customer_phone": "+2348012345678",
  "pickup_address": "12 Admiralty Way, Lekki Phase 1, Lagos",
  "dropoff_address": "45 Allen Avenue, Ikeja, Lagos",
  "package_weight_kg": "2.50",
  "declared_value": "15000.00",
  "service_level": "EXPRESS",
  "fulfillment_mode": "marketplace",
  "escrow_status": "HELD",
  "escrow_amount": "2450.00",
  "label_url": "https://api.tumr.app/api/v1/shipments/76495b28-1004-4b52-9fe1-d64e8e5ab190/label/",
  "created_at": "2026-08-14T10:15:00Z"
}

GET

Retrieve detailed state, escrow status, label URL, and ETA for a specific shipment UUID.

Authentication: Secret Key / JWT

Request ExampleHTTPS Live Endpoint

curl -X GET https://api.tumr.app/api/v1/shipments/76495b28-1004-4b52-9fe1-d64e8e5ab190/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Payload

200 OK

application/json

{
  "id": "76495b28-1004-4b52-9fe1-d64e8e5ab190",
  "tracking_number": "AKR-83491054",
  "status": "IN_TRANSIT",
  "rider": "a19c2f40-7b3e-4f9a-9d2c-5e6f7a8b9c0d",
  "rider_email": "[email protected]",
  "escrow_status": "HELD",
  "escrow_amount": "2450.00",
  "estimated_delivery": {
    "remaining_distance_km": 6.4,
    "estimated_minutes": 24,
    "eta_display": "~24 mins"
  },
  "picked_up_at": "2026-08-14T10:29:45Z",
  "created_at": "2026-08-14T10:15:00Z"
}

Previous TopicRates & Fare Calculation

Next TopicStorefront & Orders