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

ParameterTypeRequiredDescription
keystringYesClickPost API key used for authentication.
rider_availabilitybooleanNoDefault 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 NameData TypeFieldDescription
drop_latitudedoubleConditional MandatoryThe latitude of the drop location
drop_longitudedoubleConditional MandatoryThe longitude of the drop location
drop_pincodestringConditional MandatoryThe pincode of the drop location
pickup_pincodesstring[]Conditional MandatoryList of pincodes of the pickup location; Required when drop pincode is provided.
pickup_store_idsstring[]Conditional MandatoryList of pickup store ids; Required when drop latitude and longitude are provided.
optionalJSON ObjectOptionalOptional fields for the request.
reference_numberstringOptionalAn 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_latitude and drop_longitude, or drop_pincode must be provided. Both options may also be supplied together.

For Drop Location: Either pickup_pincodes or pickup_store_ids must be provided. Both options may also be supplied together.

optional object fields

Field NameData TypeFieldDescription
service_typestringOptionalSupported 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 NameData TypeDescriptionValue Constraints
metaJSON ObjectMetadata about the request, such as status codes and messages describing success or errors. Refer Possible Meta Statuses section below.cannot be null
resultJSON ObjectIncludes the serviceability results at account level.can be null or string if meta.success is false

meta object fields

Field NameData TypeDescriptionValue Constraints
messagestringHuman-readable message indicating success or describing the error.can be null or empty
statusintegerStatus code representing the result of the request (may include standard HTTP status codes).cannot be null
successbooleanIndicates whether the request was processed successfully (true) or not (false).cannot be null

result object fields

Field NameData TypeDescriptionValue Constraints
hld_etaJSON ObjectMinimum 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 storescannot be empty
slaJSON ObjectMinimum 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
eddJSON ObjectMinimum and maximum edd across all the serviceable carrier accounts. Calculated from all serviceable account's overall_edd value.cannot be empt
serviceable_accountsJSON ArrayList of hyperlocal and standard serviceable accounts with ETA (for hyperlocal) / SLA and Pricing (for standard)can be empty
request_idstringThe 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 NameData TypeDescriptionValue Constraints
minintegerThe 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
maxintegerThe 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 NameData TypeDescriptionValue Constraints
cp_idintegerCarrier Partner ID. This can be found on the dashboard or you can refer it here.cannot be null
service_typestring enumSupported Values: FORWARD, RVP If no value is passed, default FORWARD is considered.cannot be null
account_codestringCarrier partner account name configured on the Clickpost dashboard.cannot be null
account_idintegerThe identifier for the particular account configured under the carrier partner.cannot be null
mode_of_shipmentstringShipment mode supported in the account.can be null or empty
pickup_pincodestringPincode of the pickup location.can be null
drop_pincodestringPincode of the drop location.can be null
is_hldbooleanWhether account is hld (for hyperlocal) or not.cannot be null
delivery_etaintegerEstimated 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_etainteger

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 is_hld is false or if the carrier does not provide an ETA.

can be null
store_idstringIdentifier 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
serviceableJSON ObjectIndicates whether pickup is available when PICKUP is true and serviceability for other order types: COD, PREPAID, EXCHANGEcannot be null
committed_slaintegerCarrier-committed SLA (in days) uploaded in the system. Null if is_hld is true..can be null
order_to_shipintegerShipping readiness in days (0 = today, 1 = tomorrow). It depends on the configuration done in the Clickpost system.can be null
overall_slaintegerSum of committed_sla and order_to_ship (in days)can be null
eddintegerEstimated delivery details based on the configured EDD model. For more information, please refer to the Notes and Prerequisites section.can be null
overall_eddintegerSum of edd and order_to_ship (in days)can be null
shipping_chargeJSON ObjectIndicates the shipping charge for the delivery for a given order type (default is PREPAID)cannot be null

shipping_charge object fields

Field NameData TypeDescriptionValue Constraints
<OrderType>floatField Name / Key is a variable, it can either be PREPAID or COD. Value is the shipping charge for that order type.can be null
zonestringZone identified to calculate shipping charges.can be null

Possible Meta Statuses

HTTP Status Codemeta.statusmeta.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

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"
  }
}

Did this page help you?