Rider Availability (Serviceability)
API provides with the rider availability, pricing and the estimated time for pickup and drop at a carrier level.
Prerequisites
- The enterprise must be subscribed to the service.
- If a
storeIdis passed, the corresponding pickup latitude and longitude must be configured in ClickPost under Store Master. - To check serviceability for specific carriers (e.g., per dark store), set up Store–Carrier mappings in ClickPost.
Note: Contact the ClickPost team for assistance with setup and service enablement.
Allowed HTTP Methods
POST
URL
<baseURL>/api/v1/quickcom/serviceability
baseURL - https://hld.clickpost.in
Headers
{
"Content-Type": "application/json"
}URL Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | ClickPost API key used for authentication. |
Sample API cURL
curl --location --request POST '<baseURL>/api/v1/quickcom/serviceability?key=*****' \
--header 'Content-Type: application/json' \
--data '{
"pickupLat": 18.99131500,
"pickupLong": 72.8144500,
"dropLat": 19.135601,
"dropLong": 72.836901,
"storeId": null,
"referenceNumber": "testref1234",
"orderType": "PREPAID",
"itemsCount": 3,
"length": 15.4,
"height": 10.5,
"width": 20.0,
"weight": 1500,
"cpId": 220,
"accountCode": "hld_account_1",
"invoiceValue": 740.50,
"pickupPinCode": "443280",
"dropPinCode": "354320",
"pickupAddress": "",
"dropAddress": ""
}'Request Payload
| Field Name | Data Type | Field | Description |
|---|---|---|---|
pickupLat | double | Conditional Mandatory | latitude of the pickup address/store. Minimum 4 decimal places. Mandatory if storeId is not provided. Note: Higher decimal places improve serviceability accuracy. |
pickupLong | double | Conditional Mandatory | longitude of the pickup address/store. Minimum 4 decimal places. Mandatory if storeId is not provided. Note: Higher decimal places improve serviceability accuracy. |
dropLat | double | Mandatory | latitude of the drop address. Minimum 4 decimal places. Note: Higher decimal places improve serviceability accuracy. |
dropLong | double | Mandatory | longitude of the drop address. Minimum 4 decimal places. Note: Higher decimal places improve serviceability accuracy. |
storeId | string | Conditional Mandatory | Id of the dark store (it should be unique across enterprise account). Mandatory if pickupLat and pickupLong are not provided. |
referenceNumber | string | Mandatory | The reference number for the API request. Ideally it should be unique for each API request. Max allowed length is 50 characters. Allowed characters: alphanumerics and 3 special characters (-, _, .) |
orderType | enum | Mandatory | The order type for the particular shipment. Enum Values: 1. PREPAID : for prepaid order 2. COD : for cod order |
itemsCount | integer | Optional | The number of items in the order. |
length | float | Optional | Length of the overall package (in cm). Mandatory if a specific carrier requires this value to calculate the service charges. |
height | float | Optional | Height of the overall package (in cm). Mandatory if a specific carrier requires this value to calculate the service charges. |
width | float | Optional | Width of the overall package (in cm). Mandatory if a specific carrier requires this value to calculate the service charges. |
weight | integer | Optional | Weight of the package (in gm). Mandatory if a specific carrier requires this value to calculate the service charges. |
invoiceValue | float | Optional | Total invoice amount of the order in INR. Mandatory if a specific carrier requires this value to calculate the service charges. |
cpId | integer | Optional | Carrier partner ID to get the serviceability of that particular carrier partner. This can be found on the dashboard or you can refer it here. If cpId is passed, it will override the behaviour of isStoreLevelfield (if passed)and serviceability will be checked for provided cp_id carrier only. |
accountCode | string | Optional | The name of the account configured inside of the carrier partner on the Clickpost Dashboard. It should be only passed with cpId field. If passed, serviceability will be checked only for passed accountCode of cpId. If not passed, serviceability will be checked for all the active account codes of cpId. |
pickupPinCode | integer | Optional | Pin code of the pickup location. |
dropPinCode | integer | Optional | Pin code of the drop location. |
pickupAddress | string | Optional | Mandatory if a specific carrier requires this value to calculate the service charges or eta. |
dropAddress | string | Optional | Mandatory if a specific carrier requires this value to calculate the service charges or eta. |
Sample Request Payload
{
"pickupLat": 12.342123,
"pickupLong": 43.343234,
"dropLat": 54.64234232,
"dropLong": 11.22424100,
"storeId": "P_21",
"referenceNumber": "testref1234",
"orderType": "PREPAID",
"itemsCount": 3,
"length": 15.4,
"height": 10.5,
"width": 20.0,
"weight": 1500,
"invoiceValue": 740.50,
"cpId": 220,
"accountCode": "hld_account_1",
"pickupPinCode": 443280,
"dropPinCode": 354320,
"pickupAddress": "Sample Pickup Address",
"dropAddress": "Sample Drop Address"
}Response
Response JSON Format
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
metaCode | integer | It is ClickPost defined response code to provide additional context about the result of the API call. Refer Possible Meta Codes section below. | cannot be null |
response | JSON Object or string | The response data of the API request. | can be null. [low level error message can be populated here as a `string`] |
error | JSON Object | The error data of the API request. | can be null if request is successful and no error encountered. |
error fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
message | string | The high-level error message associated with metaCode to provide explanation of the encountered error. | cannot be null |
response fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
isServiceable | boolean | Indicates whether the pickup and drop latitude/longitude are serviceable by at least one carrier. Returns true if serviceable; otherwise, false. | cannot be null |
serviceableAccounts | JSON array | The serviceable carrier accounts. | empty array if isServiceable is false |
referenceNumber | string | The reference number provided in the API request body. | cannot be null |
serviceableAccounts fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
cpName | string | The name of the carrier partner. | cannot be null |
cpId | integer | Carrier Partner ID. This can be found on the dashboard or you can refer it here. | cannot be null |
accountCode | string | Carrier partner account name configured on the Clickpost dashboard. | cannot be null |
accountId | integer | The identifier for the particular account configured under the carrier partner. | cannot be null |
serviceCharges | JSON Object | It includes the delivery charge, surge charges due to rain and demand, if carrier provides it. | cannot be null |
eta | JSON Object | It includes pickup eta timestamp, drop eta timestamp and eta captured timestamp, if carrier provides it. | cannot be null |
eta fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
pickupTimestamp | timestamp | The estimated pickup datetime (in UTC) provided by the carrier, indicating when the shipment will be picked up from the enterprise’s store. Absolute pickup ETA in minutes should be calculated with respect to capturedTimestamp. | can be null if the carrier does not provide a pickup ETA. format: “YYYY-MM-DD HH:MM:SS” |
dropTimestamp | timestamp | The estimated delivery datetime (in UTC) provided by the carrier, indicating when the shipment will be delivered to the customer's location. Absolute drop ETA in minutes should be calculated with respect to capturedTimestamp. | can be null if the carrier does not provide a drop ETA. format: “YYYY-MM-DD HH:MM:SS” |
capturedTimestamp | timestamp | The UTC datetime when a response with pickup or drop ETA is received from the carrier. | can be null if the carrier does not provide either pickup or drop ETA. format: “YYYY-MM-DD HH:MM:SS” |
serviceCharges fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
deliveryCharge | float | The delivery charge (in INR) that the carrier partner will charge for the particular shipment. | can be null if carrier does not provide it. |
rainSurgeCharge | float | The rain surge charge (in INR) applicable for the service due to rain. | can be null if carrier does not provide it. |
demandSurgeCharge | float | The demand surge charge (in INR) applicable for the service due to increased demand. | can be null if carrier does not provide it. |
Possible Meta Codes
| HTTP Status Code | Meta Code | Description / Error Message |
|---|---|---|
| 200 | 200 | Request is executed successfully |
| 400 | 4001 | Invalid request json |
| 400 | 4002 | Request for invalid entity |
| 400 | 4003 | Invalid or missing query parameter |
| 400 | 4005 | User is not subscribed to the service |
| 401 | 4013 | Invalid API key |
| 403 | 403 | Access is not allowed |
| 404 | 4007 | API Not Found |
| 500 | 500 | Something went wrong in Clickpost server |
Example Responses
Success Response
{
"metaCode": 200,
"response": {
"isServiceable": true,
"serviceableAccounts": [
{
"cpName": "ShadowfaxNowSlotHLD",
"cpId": 220,
"accountCode": "Shadowfax_Now_HLD_1HR",
"accountId": 286908,
"serviceCharges": {
"deliveryCharge": 59.0,
"rainSurgeCharge": 0.0,
"demandSurgeCharge": null
},
"eta": {
"pickupTimestamp": "2025-01-01 13:20:00",
"dropTimestamp": "2025-01-01 13:40:00",
"capturedTimestamp": "2025-01-01 13:10:00"
}
},
{
"cpName": "Delhivery HLD",
"cpId": 180,
"accountCode": "Delhivery_HLD_2HR",
"accountId": 287017,
"serviceCharges": {
"deliveryCharge": 34.5,
"rainSurgeCharge": null,
"demandSurgeCharge": 10.0
},
"eta": {
"pickupTimestamp": "2025-01-01 13:20:00",
"dropTimestamp": "2025-01-01 13:40:00",
"capturedTimestamp": "2025-01-01 13:10:00"
}
}
],
"referenceNumber": "testref1234"
},
"error": null
}Error Response 1
{
"metaCode": 4001,
"response": "dropLat and dropLong are mandatory",
"error": {
"message": "Invalid request json"
}
}Error Response 2
{
"metaCode": 4002,
"response": "No Active Courier Accounts found",
"error": {
"message": "Request for invalid entity"
}
}Updated 2 days ago
Did this page help you?
