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 storeId is 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

ParameterTypeRequiredDescription
keystringYesClickPost 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 NameData TypeFieldDescription
pickupLatdoubleConditional Mandatorylatitude of the pickup address/store. Minimum 4 decimal places. Mandatory if storeId is not provided. Note: Higher decimal places improve serviceability accuracy.
pickupLongdoubleConditional Mandatorylongitude of the pickup address/store. Minimum 4 decimal places. Mandatory if storeId is not provided. Note: Higher decimal places improve serviceability accuracy.
dropLatdoubleMandatorylatitude of the drop address. Minimum 4 decimal places. Note: Higher decimal places improve serviceability accuracy.
dropLongdoubleMandatorylongitude of the drop address. Minimum 4 decimal places. Note: Higher decimal places improve serviceability accuracy.
storeIdstringConditional MandatoryId of the dark store (it should be unique across enterprise account). Mandatory if pickupLat and pickupLong are not provided.
referenceNumberstringMandatoryThe 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 (-, _, .)
orderTypeenumMandatoryThe order type for the particular shipment. Enum Values: 1. PREPAID : for prepaid order 2. COD : for cod order
itemsCountintegerOptionalThe number of items in the order.
lengthfloatOptionalLength of the overall package (in cm). Mandatory if a specific carrier requires this value to calculate the service charges.
heightfloatOptionalHeight of the overall package (in cm). Mandatory if a specific carrier requires this value to calculate the service charges.
widthfloatOptionalWidth of the overall package (in cm). Mandatory if a specific carrier requires this value to calculate the service charges.
weightintegerOptionalWeight of the package (in gm). Mandatory if a specific carrier requires this value to calculate the service charges.
invoiceValuefloatOptionalTotal invoice amount of the order in INR. Mandatory if a specific carrier requires this value to calculate the service charges.
cpIdintegerOptionalCarrier 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.
accountCodestringOptionalThe 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.
pickupPinCodeintegerOptionalPin code of the pickup location.
dropPinCodeintegerOptionalPin code of the drop location.
pickupAddressstringOptionalMandatory if a specific carrier requires this value to calculate the service charges or eta.
dropAddressstringOptionalMandatory 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 NameData TypeDescriptionValue Constraints
metaCodeintegerIt 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
responseJSON Object or stringThe response data of the API request.can be null. [low level error message can be populated here as a `string`]
errorJSON ObjectThe error data of the API request.can be null if request is successful and no error encountered.

error fields

Field NameData TypeDescriptionValue Constraints
messagestringThe high-level error message associated with metaCode to provide explanation of the encountered error.cannot be null

response fields

Field NameData TypeDescriptionValue Constraints
isServiceablebooleanIndicates whether the pickup and drop latitude/longitude are serviceable by at least one carrier. Returns true if serviceable; otherwise, false.cannot be null
serviceableAccountsJSON arrayThe serviceable carrier accounts.empty array if isServiceable is false
referenceNumberstringThe reference number provided in the API request body.cannot be null

serviceableAccounts fields

Field NameData TypeDescriptionValue Constraints
cpNamestringThe name of the carrier partner.cannot be null
cpIdintegerCarrier Partner ID. This can be found on the dashboard or you can refer it here.cannot be null
accountCodestringCarrier partner account name configured on the Clickpost dashboard.cannot be null
accountIdintegerThe identifier for the particular account configured under the carrier partner.cannot be null
serviceChargesJSON ObjectIt includes the delivery charge, surge charges due to rain and demand, if carrier provides it.cannot be null
etaJSON ObjectIt includes pickup eta timestamp, drop eta timestamp and eta captured timestamp, if carrier provides it.cannot be null

eta fields

Field NameData TypeDescriptionValue Constraints
pickupTimestamptimestampThe 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”
dropTimestamptimestampThe 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”
capturedTimestamptimestampThe 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 NameData TypeDescriptionValue Constraints
deliveryChargefloatThe delivery charge (in INR) that the carrier partner will charge for the particular shipment.can be null if carrier does not provide it.
rainSurgeChargefloatThe rain surge charge (in INR) applicable for the service due to rain.can be null if carrier does not provide it.
demandSurgeChargefloatThe 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 CodeMeta CodeDescription / Error Message
200200Request is executed successfully
4004001Invalid request json
4004002Request for invalid entity
4004003Invalid or missing query parameter
4004005User is not subscribed to the service
4014013Invalid API key
403403Access is not allowed
4044007API Not Found
500500Something 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"
  }
}

Did this page help you?