API - Shipment Rate

Created by KloudShip Support, Modified on Fri, 24 Oct at 7:39 PM by KloudShip Support

POST: ShipmentRate

This document provides information about the `POST /api/v1/ShipmentRate` endpoint, which allows you to get shipment rate estimates for a given shipment request.
This API retrieves available shipping rates for the given shipment details including source, destination, package dimensions, and weight.
It helps determine shipping costs and available carrier services before creating a shipment.

Endpoint details

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/ShipmentRate
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/ShipmentRate
Content-Type	application/json

Request body:

Field	Type	Required	Description
`addressFrom`	`object`	Yes	Sender's address details
`addressTo`	`object`	Yes	Receiver's address details
`locationId`	`string`	No	The warehouse or origin location ID
`packages`	`array`	Yes	List of package details (dimensions, weight, etc.)
`items`	`array`	Yes	List of shipment items with product and tax details
`specialServices`	`array`	No	Optional special services such as insurance, COD and OTP required
`isTest`	`boolean`	No	Indicates whether the request is for test mode (`true` or `false`)

Address Object Structure:

Field	Type	Required	Description
`firstname`	`string`	Yes	Contact first name
`lastname`	`string`	No	Contact last name
`company`	`string`	No	Company name
`street1`	`string`	Yes	Primary street address
`street2`, `street3`	`string`	No	Additional address lines
`city`	`string`	Yes	City name
`stateCode`	`string`	Yes	Two-letter state code (e.g., `MH`, `UP`)
`zip`	`string`	Yes	Postal code
`countryCode`	`string`	No	Country code (`IN` for India)
`phone`	`string`	Yes	Contact number
`email`	`string`	No	Contact email
`save`	`boolean`	No	Whether to save address
`verify`	`boolean`	No	Whether to verify address
`isResidential`	`boolean`	No	Whether the address is residential
`latitude`	`number`	No	Geographical latitude
`longitude`	`number`	No	Geographical longitude

Package Object Structure:

Field	Type	Required	Description
`name`	`string`	No	Package name or description
`length`	`number`	Yes	Length of the package
`width`	`number`	Yes	Width of the package
`height`	`number`	Yes	Height of the package
`dimensionUnit`	`string`	No	Dimension unit (`cm`, `in`)
`weight`	`number`	Yes	Package weight
`weightUnit`	`string`	No	Weight unit (`kg`, `g`, `lb`)

Item Object Structure:

Field	Type	Required	Description
`productId`	`string`	Yes	Unique product identifier
`productName`	`string`	Yes	Product name
`name`	`string`	Yes	Item name
`weight`	`number`	Yes	Item weight
`weightUnit`	`string`	No	Weight unit (`g`, `kg`)
`totalValue`	`number`	Yes	Total item value (including tax)
`value`	`number`	No	Item base value
`taxInfos`	`array`	No	Tax details applied to the item

Tax Info Object:

Field	Type	Description
`code`	`string`	Tax type (e.g., `IGST`, `SGST`)
`value`	`string`	Tax value amount

Example:

{
    "addressFrom": {
        "firstname": "Nisha",
        "lastname": "Thuwal",
        "company": "Bharti Creations",
        "street1": "Bharti Creations, Gaon Bhag",
        "street2": "",
        "street3": "",
        "city": "Sangli",
        "stateCode": "MH",
        "zip": "416416",
        "countryCode": "IN",
        "phone": "9999999999",
        "email": "aackl@abc.com",
        "save": false,
        "verify": false,
        "isResidential": false,
        "latitude": 16.8597981,
        "longitude": 74.5635889
    },
    "locationId": "6784fed7326a0ee24be9f4f7",
    // "carrierAccountId": "",
    // "service": "Surface",
    "addressTo": {
        "firstname": "ABC",
        "lastname": "xyz",
        "company": "Impledge Technologies",
        "street1": "5TH FLOOR, REGUS, TOWER C",
        "street2": "Green Boulevard, B-BLOCK",
        "street3": "",
        "city": "Gautam Buddha Nagar",
        "stateCode": "UP",
        "zip": "201309",
        "countryCode": "IN",
        "phone": "9999999999",
        "email": "xyz@gmail.com",
        "save": false,
        "verify": true,
        "isResidential": false,
        "latitude": 28.6228797,
        "longitude": 77.3672554
    },
    "packages": [
        {
            "name": "Watch Box",
            "length": 10.0,
            "width": 10.0,
            "height": 5.0,
            "dimensionUnit": "cm",
            "weight": 1.64,
            "weightUnit": "kg"
        }
    ],
    "items": [
        {
            "productId": "58712aebe8f048ec902bcc6c2d06426c",
            "productName": "Used Watch",
            "name": "Used Watch",
            "weight": 1000.0,
            "weightUnit": "g",
            "totalValue": 599.0,
            "value": 500.0,
            "taxInfos": [
                {
                    "code": "IGST",
                    "value": "99"
                }
            ]
        }
    ],
    "specialServices": [
        // {
        //     "code": "Insure",
        //     "parameters": [
        //         {
        //             "code": "Amount",
        //             "value": "50"
        //         }
        //     ]
        // }
    ],
    "isTest": false
}

cURL:

curl --location 'https://api-ppd.kloudship.com:960/api/v1/ShipmentRate' \
--header 'transactionId: 10001' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer *****' \
--data-raw '{
    "addressFrom": {
        "firstname": "Nisha",
        "lastname": "Thuwal",
        "company": "Bharti Creations",
        "street1": "Bharti Creations, Gaon Bhag",
        "street2": "",
        "street3": "",
        "city": "Sangli",
        "stateCode": "MH",
        "zip": "416416",
        "countryCode": "IN",
        "phone": "9999999999",
        "email": "aackl@abc.com",
        "save": false,
        "verify": false,
        "isResidential": false,
        "latitude": 16.8597981,
        "longitude": 74.5635889
    },
    "locationId": "6784fed7326a0ee24be9f4f7",
    "addressTo": {
        "firstname": "ABC",
        "lastname": "xyz",
        "company": "Impledge Technologies",
        "street1": "5TH FLOOR, REGUS, TOWER C",
        "street2": "Green Boulevard, B-BLOCK",
        "street3": "",
        "city": "Gautam Buddha Nagar",
        "stateCode": "UP",
        "zip": "201309",
        "countryCode": "IN",
        "phone": "9999999999",
        "email": "xyz@gmail.com",
        "save": false,
        "verify": true,
        "isResidential": false,
        "latitude": 28.6228797,
        "longitude": 77.3672554
    },
    "packages": [
        {
            "name": "Watch Box",
            "length": 10.0,
            "width": 10.0,
            "height": 5.0,
            "dimensionUnit": "cm",
            "weight": 1.64,
            "weightUnit": "kg"
        }
    ],
    "items": [
        {
            "productId": "58712aebe8f048ec902bcc6c2d06426c",
            "productName": "Used Watch",
            "name": "Used Watch",
            "weight": 1000.0,
            "weightUnit": "g",
            "totalValue": 599.0,
            "value": 500.0,
            "taxInfos": [
                {
                    "code": "IGST",
                    "value": "99"
                }
            ]
        }
    ],
    "specialServices": [
       
    ],
    "isTest": false
}'

Response example:

{
    "rates": [
        {
            "valueCurrency": "INR",
            "totalFee": 110.33000,
            "finalWeight": 1.640,
            "finalVolume": 500.000,
            "fee": [
                {
                    "packageNumber": 1,
                    "cost": 76.500,
                    "costType": "Base"
                },
                {
                    "packageNumber": 1,
                    "cost": 17.0,
                    "costType": "Surcharge"
                },
                {
                    "packageNumber": 1,
                    "cost": 16.83000,
                    "costType": "Tax"
                }
            ],
            "finalWeightUnit": "kg",
            "finalDimensionUnit": "cm",
            "carrierAccountId": "670ca084323de7c806a1e652",
            "carrier": "Delhivery",
            "carrierAccountName": "Delhivery",
            "category": "Native",
            "service": "Surface",
            "specialServices": []
        },
        {
            "valueCurrency": "INR",
            "totalFee": 110.33000,
            "finalWeight": 1.640,
            "finalVolume": 500.000,
            "fee": [
                {
                    "packageNumber": 1,
                    "cost": 76.500,
                    "costType": "Base"
                },
                {
                    "packageNumber": 1,
                    "cost": 17.0,
                    "costType": "Surcharge"
                },
                {
                    "packageNumber": 1,
                    "cost": 16.83000,
                    "costType": "Tax"
                }
            ],
            "finalWeightUnit": "kg",
            "finalDimensionUnit": "cm",
            "carrierAccountId": "670ca084323de7c806a1e652",
            "carrier": "Delhivery",
            "carrierAccountName": "Delhivery",
            "category": "Native",
            "service": "Express",
            "specialServices": []
        },
        {
            "valueCurrency": "INR",
            "totalFee": 125.90600,
            "finalWeight": 1.64,
            "finalVolume": 500.000,
            "deliveryDays": 2,
            "deliveryDate": "2025-10-15T16:19:28.5508071Z",
            "fee": [
                {
                    "packageNumber": 1,
                    "cost": 106.700,
                    "costType": "Base"
                },
                {
                    "packageNumber": 1,
                    "cost": 19.20600,
                    "costType": "Tax"
                }
            ],
            "finalWeightUnit": "kg",
            "finalDimensionUnit": "cm",
            "carrierAccountId": "670ca085323de7c806a1e654",
            "carrier": "XpressBees",
            "carrierAccountName": "XpressBees",
            "category": "Native",
            "service": "Surface",
            "specialServices": []
        },
        {
            "valueCurrency": "INR",
            "totalFee": 61.49000,
            "finalWeight": 2.0,
            "finalVolume": 500.000,
            "deliveryDays": 0,
            "deliveryDate": "2025-10-13T18:00:00Z",
            "categories": [
                "Cheapest"
            ],
            "fee": [
                {
                    "packageNumber": 1,
                    "cost": 60.500,
                    "costType": "Base"
                },
                {
                    "packageNumber": 1,
                    "cost": 0.99000,
                    "costType": "Tax"
                }
            ],
            "finalWeightUnit": "kg",
            "finalDimensionUnit": "cm",
            "carrierAccountId": "670ca085323de7c806a1e655",
            "carrier": "Borzo",
            "carrierAccountName": "Borzo",
            "category": "Native",
            "service": "Surface",
            "specialServices": []
        },
        {
            "valueCurrency": "INR",
            "totalFee": 110.33000,
            "finalWeight": 1.64,
            "finalVolume": 500.000,
            "deliveryDays": 4,
            "deliveryDate": "2025-10-17T16:19:28.7893392Z",
            "fee": [
                {
                    "packageNumber": 1,
                    "cost": 76.500,
                    "costType": "Base"
                },
                {
                    "packageNumber": 1,
                    "cost": 17.0,
                    "costType": "Surcharge"
                },
                {
                    "packageNumber": 1,
                    "cost": 16.83000,
                    "costType": "Tax"
                }
            ],
            "finalWeightUnit": "kg",
            "finalDimensionUnit": "cm",
            "carrierAccountId": "6778182c3c1cd7574c4e8768",
            "carrier": "Ekart",
            "carrierAccountName": "Ekart",
            "category": "Native",
            "service": "Surface",
            "specialServices": []
        },
        {
            "valueCurrency": "INR",
            "totalFee": 116.82000,
            "finalWeight": 1.64,
            "finalVolume": 500.000,
            "deliveryDays": 4,
            "deliveryDate": "2025-10-17T16:19:30.649677Z",
            "fee": [
                {
                    "packageNumber": 1,
                    "cost": 99.000,
                    "costType": "Base"
                },
                {
                    "packageNumber": 1,
                    "cost": 17.82000,
                    "costType": "Tax"
                }
            ],
            "finalWeightUnit": "kg",
            "finalDimensionUnit": "cm",
            "carrierAccountId": "6880a6f0e32e19eea1a57b15",
            "carrier": "EkartElite",
            "carrierAccountName": "Ekart Elite",
            "category": "Native",
            "service": "Surface",
            "specialServices": []
        },
        {
            "valueCurrency": "INR",
            "totalFee": 95.65608,
            "finalWeight": 1.64,
            "finalVolume": 9052.560,
            "deliveryDays": 0,
            "deliveryDate": "2025-10-13T18:19:28.9931449Z",
            "categories": [
                "Fastest"
            ],
            "fee": [
                {
                    "packageNumber": 1,
                    "cost": 94.116,
                    "costType": "Base"
                },
                {
                    "packageNumber": 1,
                    "cost": 1.54008,
                    "costType": "Tax"
                }
            ],
            "finalWeightUnit": "kg",
            "finalDimensionUnit": "cm",
            "carrierAccountId": "68e02252392381e9215a83a3",
            "carrier": "Porter",
            "carrierAccountName": "Porter",
            "category": "Native",
            "service": "Surface",
            "specialServices": []
        }
    ],
    "errors": [],
    "warnings": [
        {
            "module": "ShipmentRate",
            "message": "Origin pin not serviceable.",
            "source": "KloudShip.CSA.Delhivery",
            "carrierCode": "Delhivery"
        },
        {
            "module": "ShipmentRate",
            "message": "Origin pin not serviceable.",
            "source": "KloudShip.CSA.Delhivery",
            "carrierCode": "Delhivery"
        }
    ]
}

Response object structure:

Root Level

Field	Type	Description
`rates`	`array`	List of available carrier rate details
`errors`	`array`	List of errors (if any occurred)
`warnings`	`array`	List of warnings such as non-serviceable routes

Rate Object

Field	Type	Description
`valueCurrency`	`string`	Currency code (e.g., `INR`)
`totalFee`	`number`	Total shipping cost (sum of base, surcharge, tax, etc.)
`finalWeight`	`number`	Final weight considered for rate calculation
`finalVolume`	`number`	Volume of package in cubic centimeters
`fee`	`array`	Detailed cost breakdown
`finalWeightUnit`	`string`	Unit of weight (e.g., `kg`)
`finalDimensionUnit`	`string`	Unit of dimensions (e.g., `cm`)
`carrierAccountId`	`string`	Unique ID of the carrier account
`carrier`	`string`	Carrier name (e.g., Delhivery, Ekart, Borzo)
`carrierAccountName`	`string`	Display name of the carrier account
`category`	`string`	Type of integration (e.g., `Native`)
`service`	`string`	Carrier service type (e.g., `Surface`, `Express`)
`deliveryDays`	`number`	Estimated delivery days (optional)
`deliveryDate`	`string`	Estimated delivery date and time (ISO format)
`categories`	`array`	Additional classification (e.g., `Cheapest`, `Fastest`)
`specialServices`	`array`	Applied optional services, if any

Fee Object

Field	Type	Description
`packageNumber`	`number`	Package index number
`cost`	`number`	Cost amount
`costType`	`string`	Type of charge (`Base`, `Surcharge`, `Tax`)

Warnings Object

Field	Type	Description
`module`	`string`	Module where warning occurred
`message`	`string`	Warning message
`source`	`string`	Source module or component
`carrierCode`	`string`	Carrier associated with the warning

Example Use Cases

To compare rates from different carriers for a given route.
To select the cheapest or fastest carrier before creating a shipment.
To verify carrier serviceability between the source and destination.

Notes

When the origin or destination PIN is not serviceable by a carrier, the response includes a warning under the warnings array.
The API may return multiple rate options for the same carrier (e.g., Surface, Express).
categories like Cheapest and Fastest are provided for quick decision-making.

Not Yet Signed Up?

Get started with KloudShip - This article explains steps like signing up, KYC, and adding balance to your account