Unified Serviceability
This API checks the serviceability for hyperlocal (optionally rider availability) and standard delivery for given pickup and drop locations based on the system setup/configuration and provides delivery ETA (for hyperlocal), EDD and SLA with shipping charges (for standard).
Prerequisites
- The enterprise must be subscribed to the service.
- The following configuration must be present in the ClickPost system:
- Store Master Configuration
- Store ↔ Courier Mapping
- To get the delivery ETA for the serviceable pickup store(s)
- Distance (Lat/Long) based ETA Configuration
- Pincode based ETA Configuration
- For the rider availability check - configured carriers should have the supporting APIs.
- For the standard serviceability to be calculated - following configuration must be present:
- Pincode level serviceability to be configured for the carrier.
- Pincode level SLA to be uploaded for the carrier.
- To include the Pricing for the serviceable standard pincodes, Pincode-Zone level Pricing to be uploaded for the carrier.
- The required EDD Type, Holiday, Cutoff, Delay, Enterprise-specific custom logic, and applicable EDD Model configurations must be configured before calculating EDD/SLA.
The following EDD configuration models supported here are :- Uploaded SLA - The enterprise provides the SLA configuration, which is used for calculating the EDD.
- ClickPost EDD - The EDD is calculated by ClickPost. The underlying EDD model is selected and managed internally by the clickpost team based on the enterprise configuration. Supported models include:
- Statistical Model – Calculates EDD using statistical data based on factors such as pickup, drop, courier account, and other relevant parameters.
- Data Science Model – Uses precomputed data generated by the Data Science model and stored in Scylla.
- Heavy Shipment Statistical Model – A statistical model specifically used for heavy shipments and enabled for selected enterprises.
- Combination EDD - The enterprise can configure a priority order across multiple EDD sources. For example, Uploaded SLA → ClickPost EDD, where the next source is used based on the configured combination and availability.
Note: Contact the ClickPost team for assistance with setup.
Note
- HLD: Stores that are not operational (i.e., outside their configured operating hours) will be excluded from the API response.
- Standard Delivery: Accounts that are blacklisted will be excluded from SLA calculation and will not be considered for the API response.
- Standard Delivery: The returned EDD/SLA is a single final calculated value that incorporates all applicable configurations, including EDD Type, Holiday, Cutoff, Delay, Enterprise-specific custom logic, and the applicable EDD Model configured.
- Standard Delivery: If the configured EDD source does not have a valid entry for the given pickup and drop combination, the default Statistical Model is used as a fallback. If the default Statistical Model also cannot determine a valid EDD, a default configurable EDD value of min = 2, max = 5 can be configured and returned as per requirement.
Allowed HTTP Methods
POST
URL
<baseURL>/api/v1/unified_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. |
rider_availability | boolean | No | Default value is false.If passed true, real time rider availability will be checked for the hyperlocal carriers at store level and serviceability result will be populated in the serviceable.COD and serviceable.PREPAID fields. |
Sample API cURL
curl -X POST "<baseURL>/api/v1/unified_serviceability?key=<API_KEY>&rider_availability=false" \
-H "Content-Type: application/json" \
-d '{
"reference_number": "test_reference_1",
"drop_pincode": "110094",
"pickup_pincodes": [
"560055",
"302017",
"400070",
"560048",
"110078"
],
"drop_latitude": 12.123421,
"drop_longitude": 13.3223223,
"pickup_store_ids": [
"store_1",
"store_2",
"store_3"
],
"optional": {
"service_type": "FORWARD"
}
}'Request Payload
| Field Name | Data Type | Field | Description |
|---|---|---|---|
drop_latitude | double | Conditional Mandatory | The latitude of the drop location |
drop_longitude | double | Conditional Mandatory | The longitude of the drop location |
drop_pincode | string | Conditional Mandatory | The pincode of the drop location |
pickup_pincodes | string[] | Conditional Mandatory | List of pincodes of the pickup location; Required when drop pincode is provided. |
pickup_store_ids | string[] | Conditional Mandatory | List of pickup store ids; Required when drop latitude and longitude are provided. |
optional | JSON Object | Optional | Optional fields for the request. |
reference_number | string | Optional | An optional unique identifier provided by the caller/source for a request. It can be used to trace and correlate the request across logs and systems. |
For Pickup Location: Either
drop_latitudeanddrop_longitude, ordrop_pincodemust be provided. Both options may also be supplied together.For Drop Location: Either
pickup_pincodesorpickup_store_idsmust be provided. Both options may also be supplied together.
optional object fields
| Field Name | Data Type | Field | Description |
|---|---|---|---|
service_type | string | Optional | Supported Values: FORWARD, RVP If no value is passed, default FORWARD is considered. |
Sample Request Payload
{
"reference_number": "test_reference_1",
"drop_pincode": "110094",
"pickup_pincodes": [
"560055",
"302017",
"400070",
"560048",
"110078"
],
"drop_latitude": 12.123421,
"drop_longitude": 13.3223223,
"pickup_store_ids": [
"store_1",
"store_2",
"store_3"
],
"optional": {
"service_type": "FORWARD"
}
}Response JSON Format
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
meta | JSON Object | Metadata about the request, such as status codes and messages describing success or errors. Refer Possible Meta Statuses section below. | cannot be null |
result | JSON Object | Includes the serviceability results at account level. | can be null or string if meta.success is false |
meta object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
message | string | Human-readable message indicating success or describing the error. | can be null or empty |
status | integer | Status code representing the result of the request (may include standard HTTP status codes). | cannot be null |
success | boolean | Indicates whether the request was processed successfully (true) or not (false). | cannot be null |
result object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
hld_eta | JSON Object | Minimum and maximum delivery ETA(in minutes) across hld stores. A given store might have multiple carriers servicing it. It takes into account the max and min across all the stores | cannot be empty |
sla | JSON Object | Minimum and maximum committed delivery SLA (in days) (Carrier uploaded SLA)across all the serviceable carrier accounts . Calculated from all serviceable account's overall_sla value. | cannot be empty |
edd | JSON Object | Minimum and maximum edd across all the serviceable carrier accounts. Calculated from all serviceable account's overall_edd value. | cannot be empt |
serviceable_accounts | JSON Array | List of hyperlocal and standard serviceable accounts with ETA (for hyperlocal) / SLA and Pricing (for standard) | can be empty |
request_id | string | The unique request identifier generated by ClickPost for each API request, used for tracing and debugging logs. | cannot be null |
hld_eta, sla & edd object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
min | integer | The minimum ETA (in minutes), SLA (in days), or EDD (in days) value across all serviceable accounts. ETA is sourced from ClickPost's static config (delivery_eta), not the carrier-provided courier_delivery_eta. | can be null |
max | integer | The maximum ETA (in minutes), SLA (in days), or EDD (in days) value across all serviceable accounts. ETA is sourced from ClickPost's static config (delivery_eta), not the carrier-provided courier_delivery_eta. | can be null |
serviceable_accounts object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
cp_id | integer | Carrier Partner ID. This can be found on the dashboard or you can refer it here. | cannot be null |
service_type | string enum | Supported Values: FORWARD, RVP If no value is passed, default FORWARD is considered. | cannot be null |
account_code | string | Carrier partner account name configured on the Clickpost dashboard. | cannot be null |
account_id | integer | The identifier for the particular account configured under the carrier partner. | cannot be null |
mode_of_shipment | string | Shipment mode supported in the account. | can be null or empty |
pickup_pincode | string | Pincode of the pickup location. | can be null |
drop_pincode | string | Pincode of the drop location. | can be null |
is_hld | boolean | Whether account is hld (for hyperlocal) or not. | cannot be null |
delivery_eta | integer | Estimated delivery time in minutes, based on the static configuration set in ClickPost for the account's carrier. Null if is_hld is false. | can be null |
courier_delivery_eta | integer | Estimated delivery time in minutes, as provided by the carrier. (Only when rider_availability =true, carrier's rider availability API is called and the dynamic ETA returned by carrier is populated) Returns the higher value between COD and PREPAID ETA when no order type is specified. Null if | can be null |
store_id | string | Identifier of the HLD store. pickup_store_ids field in the request will have this value only. This stays null when is_hld is false. | can be null |
serviceable | JSON Object | Indicates whether pickup is available when PICKUP is true and serviceability for other order types: COD, PREPAID, EXCHANGE | cannot be null |
committed_sla | integer | Carrier-committed SLA (in days) uploaded in the system. Null if is_hld is true.. | can be null |
order_to_ship | integer | Shipping readiness in days (0 = today, 1 = tomorrow). It depends on the configuration done in the Clickpost system. | can be null |
overall_sla | integer | Sum of committed_sla and order_to_ship (in days) | can be null |
edd | integer | Estimated delivery details based on the configured EDD model. For more information, please refer to the Notes and Prerequisites section. | can be null |
overall_edd | integer | Sum of edd and order_to_ship (in days) | can be null |
shipping_charge | JSON Object | Indicates the shipping charge for the delivery for a given order type (default is PREPAID) | cannot be null |
shipping_charge object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
<OrderType> | float | Field Name / Key is a variable, it can either be PREPAID or COD. Value is the shipping charge for that order type. | can be null |
zone | string | Zone identified to calculate shipping charges. | can be null |
Possible Meta Statuses
| HTTP Status Code | meta.status | meta.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
Sample Success Response
{
"result": {
"hld_eta": {
"min": 30,
"max": 75
},
"sla": {
"min": 2,
"max": 5
},
"edd": {
"min": 3,
"max": 3
},
"serviceable_accounts": [
{
"cp_id": 180,
"service_type": "FORWARD",
"account_code": "delhivery_hld_test",
"account_id": 187852,
"mode_of_shipment": "HYPERLOCAL",
"pickup_pincode": "560055",
"drop_pincode": "110094",
"is_hld": true,
"delivery_eta": 75,
"courier_delivery_eta": null,
"store_id": "store_1",
"serviceable": {
"COD": null,
"PREPAID": null,
"EXCHANGE": null,
"PICKUP": null
},
"committed_sla": null,
"overall_sla": null,
"order_to_ship": null,
"edd": null,
"overall_edd": null,
"shipping_charge": {
"PREPAID": null,
"zone": null
}
},
{
"cp_id": 364,
"service_type": "FORWARD",
"account_code": "porter_hld_test",
"account_id": 141231,
"mode_of_shipment": "",
"pickup_pincode": "560054",
"drop_pincode": "110094",
"is_hld": true,
"delivery_eta": 30,
"courier_delivery_eta": 75,
"store_id": "store_2",
"serviceable": {
"COD": null,
"PREPAID": null,
"EXCHANGE": null,
"PICKUP": null
},
"committed_sla": null,
"overall_sla": null,
"order_to_ship": null,
"edd": null,
"overall_edd": null,
"shipping_charge": {
"PREPAID": null,
"zone": null
}
},
{
"cp_id": 632,
"service_type": "FORWARD",
"account_code": "blitz_hld_test",
"account_id": 151241,
"mode_of_shipment": "HYPERLOCAL",
"pickup_pincode": "560055",
"drop_pincode": "110094",
"is_hld": true,
"delivery_eta": null,
"courier_delivery_eta": 45,
"store_id": "store_3",
"serviceable": {
"COD": null,
"PREPAID": null,
"EXCHANGE": null,
"PICKUP": null
},
"committed_sla": null,
"overall_sla": null,
"order_to_ship": null,
"edd": null,
"overall_edd": null,
"shipping_charge": {
"PREPAID": null,
"zone": null
}
},
{
"cp_id": 5,
"service_type": "FORWARD",
"account_code": "bd_test1",
"account_id": 231412,
"mode_of_shipment": "SURFACE",
"pickup_pincode": "560055",
"drop_pincode": "110094",
"is_hld": false,
"delivery_eta": null,
"courier_delivery_eta": null,
"store_id": null,
"serviceable": {
"COD": true,
"PREPAID": true,
"EXCHANGE": false,
"PICKUP": true
},
"committed_sla": 4,
"order_to_ship": 1,
"overall_sla": 5,
"edd": 2,
"overall_edd": 3,
"shipping_charge": {
"PREPAID": 76.5,
"zone": "CITY"
}
},
{
"cp_id": 9,
"service_type": "FORWARD",
"account_code": "sfx_test1",
"account_id": 231412,
"mode_of_shipment": "SURFACE",
"pickup_pincode": "560054",
"drop_pincode": "110094",
"is_hld": false,
"delivery_eta": null,
"courier_delivery_eta": null,
"store_id": null,
"serviceable": {
"COD": true,
"PREPAID": false,
"EXCHANGE": false,
"PICKUP": true
},
"committed_sla": 2,
"order_to_ship": null,
"overall_sla": 2,
"edd": 3,
"overall_edd": 3,
"shipping_charge": {
"PREPAID": null,
"zone": null
}
},
{
"cp_id": 4,
"service_type": "FORWARD",
"account_code": "del_test1",
"account_id": 231412,
"mode_of_shipment": "SURFACE",
"pickup_pincode": "560053",
"drop_pincode": "110094",
"is_hld": false,
"delivery_eta": null,
"courier_delivery_eta": null,
"store_id": null,
"serviceable": {
"COD": true,
"PREPAID": false,
"EXCHANGE": false,
"PICKUP": true
},
"committed_sla": null,
"order_to_ship": 1,
"overall_sla": null,
"edd": null,
"overall_edd": null,
"shipping_charge": {
"PREPAID": 56.75,
"zone": null
}
}
],
"request_id": "8668f578-35bd-4a54-8bb2-329e4376e9a5"
},
"meta": {
"status": 200,
"success": true,
"message": "Request is executed successfully"
}
}Sample Error Response
{
"result": "Both drop_latitude and drop_longitude must be provided together",
"meta": {
"status": 4001,
"success": false,
"message": "Invalid request json"
}
}Updated about 2 months ago
