Get Shipping Quote
Calculate the full cost breakdown for a route before creating a shipment. Use this to display pricing to your users without booking anything or touching the wallet.
Endpoint
POST
/v1/shipments/calculate-ratesRequired permission: shipments:quote:get
How the Pricing Works
Rates are computed from three components stacked on top of a base fare:
| Component | Rule |
|---|---|
| Base fare | Flat charge applied to every shipment |
| Distance fee | Per-kilometer charge multiplied by route distance |
| Weight surcharge | Tiered charge based on the selected packageCategory |
| Value surcharge | Applied when enableInsurance is true. a percentage of itemValue |
The exact rates (base fare, per-km rate, surcharge amounts) are configured per-workspace in your settings. The quote endpoint uses your workspace's active pricing config.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
originPlaceId | String | ✅ | Google Maps Place ID of the pickup location. |
destPlaceId | String | ✅ | Google Maps Place ID of the delivery location. |
packageCategory | String | ✅ | Size tier. One of SMALL, MEDIUM, LARGE, or EXTRA_LARGE. |
itemValue | Integer | ❌ | Declared item value in ₦. Used to calculate insurance surcharge. |
enableInsurance | Boolean | ❌ | Pass true to include the value surcharge in the quote. |
Response
| Field | Type | Description |
|---|---|---|
baseFare | Number | Flat base rate in ₦. |
distanceFee | Number | Distance charge in ₦. |
weightSurcharge | Number | Package category surcharge in ₦. |
valueSurcharge | Number | Insurance surcharge in ₦ (zero if not requested). |
totalCost | Number | Sum of all components in ₦. |
{
"originPlaceId": "ChIJi4eLcz4OdkgRlgpAD5e4OCg",
"destPlaceId": "ChIJv1SCIS2TOxARgv6-Zj4i_yw",
"packageCategory": "MEDIUM",
"itemValue": 450000,
"enableInsurance": true
}