Rates & Fare Calculation

Compare multi-carrier pricing estimates, express riders, and carrier fleets before dispatching packages.

POST

Stateless multi-carrier rate estimation endpoint (Shippo-style). Evaluates on-demand Express Rider delivery (for distances <= 40km) alongside active Carrier Fleet linehaul options and nearby pickup points. Returns cryptographic rate_tokens used to lock prices upon shipment creation. (Alias: /api/v1/quotes/rates/)

Authentication: Secret Key / JWT

Request Body Fields

Field	Type	Requirement	Description
pickup_latitude	decimal	Required	Latitude coordinate of the pickup location.
pickup_longitude	decimal	Required	Longitude coordinate of the pickup location.
dropoff_latitude	decimal	Required	Latitude coordinate of the delivery destination.
dropoff_longitude	decimal	Required	Longitude coordinate of the delivery destination.
package_weight_kg	decimal	Optional	Actual package weight in kilograms. Default: `0.00`
declared_value	decimal	Optional	Declared item value in local currency (used for insurance & Saver eligibility). Default: `0.00`
pickup_country	string	Optional	Two-letter ISO country code for pickup. Nigeria is the only live market today. Allowed:`"NG"` Default: `NG`
dropoff_country	string	Optional	Two-letter ISO country code for dropoff (must match pickup country). Default: `NG`
length_cm	decimal	Optional	Package length in cm for volumetric weight calculation.
width_cm	decimal	Optional	Package width in cm for volumetric weight calculation.
height_cm	decimal	Optional	Package height in cm for volumetric weight calculation.
fulfillment_mode	string	Optional	Optional filter for specific fulfillment stream. Allowed:`"marketplace""carrier"`

Request ExampleHTTPS Live Endpoint

curl -X POST https://api.tumr.app/api/v1/rates/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_latitude": 6.4281,
    "pickup_longitude": 3.4219,
    "dropoff_latitude": 6.5244,
    "dropoff_longitude": 3.3792,
    "package_weight_kg": 2.5,
    "declared_value": 15000.00,
    "pickup_country": "NG"
  }'

Response Payload

201 Created

application/json

{
  "direct_distance_km": "11.62",
  "is_rider_coverable": true,
  "recommended_mode": "marketplace",
  "currency": "NGN",
  "rates": [
    {
      "rate_id": "rate_mkp_exp_8820ab12",
      "rate_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxmaWxsbWVudF9tb2RlIjoibWFya2V0cGxhY2UiLCJzZXJ2aWNlX2xldmVsIjoiRVhQUkVTUyIsInRvdGFsIjoiMjQ1MC4wMCJ9...",
      "fulfillment_mode": "marketplace",
      "service_level": "EXPRESS",
      "service_name": "Express Rush Delivery",
      "provider": "Tumr Marketplace Rider Network",
      "total": "2450.00",
      "currency": "NGN",
      "distance_km": "11.62",
      "package_size_class": "SMALL",
      "estimated_duration_minutes": 29,
      "estimated_delivery_display": "~29 mins",
      "badge": "express / On-Demand",
      "is_rider_delivery": true,
      "breakdown": {
        "base_fare": "1500.00",
        "distance_fee": "800.00",
        "weight_fee": "150.00",
        "value_surcharge": "0.00",
        "protection_fee": "0.00"
      }
    },
    {
      "rate_id": "rate_car_cp_1029",
      "rate_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmdWxmaWxsbWVudF9tb2RlIjoiY2FycmllciIsInRvdGFsIjoiMzIwMC4wMCJ9...",
      "carrier_id": "84810283-4910-4821-b391-491028491024",
      "carrier_name": "Partner Carrier Fleet",
      "fulfillment_mode": "carrier",
      "service_level": "STANDARD",
      "service_name": "Partner Carrier Fleet Delivery",
      "provider": "Partner Carrier",
      "total": "3200.00",
      "currency": "NGN",
      "distance_km": "11.62",
      "badge": "Carrier Fleet",
      "is_rider_delivery": false,
      "first_mile": {
        "available": true,
        "fee": "750.00",
        "service_level": "SAME_DAY"
      },
      "combined_pickup_total": "3950.00"
    }
  ],
  "marketplace_rates": [...],
  "carrier_rates": [...],
  "pickup_points": [],
  "package_size_class": "SMALL"
}

Previous TopicAuthentication & Tokens

Next TopicShipments & Bookings