Recommendation

It helps select the appropriate carrier at a store level.

Prerequisites

  • The enterprise must be subscribed to the service.
  • The Store Master configuration must be set up in ClickPost.
  • Store–Carrier mapping.
  • Recommendation Rule Setup
  • Rule Mapping to the Store

Note: Contact the ClickPost team for assistance with setup and service enablement.

Note

  • If the requested store is not operational (i.e., outside its configured operating hours), the API will return an error response.

Allowed HTTP Methods

  • POST

URL

<baseURL>/api/v1/quickcom/recommendation

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/recommendation?key=*****' \
--header 'Content-Type: application/json' \
--data '{
    "pickup_lat": null,
    "pickup_long": null,
    "drop_lat": 13.002060,
    "drop_long": 77.631691,
    "store_id": "TEST_STORE",
    "reference_number": "testref1234",
    "order_type": "COD",
    "pickup_pincode": null,
    "drop_pincode": null,
    "invoice_value": 200.45,
    "cod_value": 200.65,
    "brand_eta": 20
}'

Request Payload

Field NameData TypeFieldDescription
pickup_latdoubleConditional Mandatorylatitude of the pickup address/store. Minimum 4 decimal places. Mandatory if store_id is not provided. Note: Higher decimal places improve serviceability accuracy. If store_id also provided along with pickup_lat and pickup_long , first precedence is given to store_id only.
pickup_longdoubleConditional Mandatorylongitude of the pickup address/store. Minimum 4 decimal places. Mandatory if store_idis not provided. Note: Higher decimal places improve serviceability accuracy.
drop_latdoubleMandatorylatitude of the drop address. Minimum 4 decimal places. Note: Higher decimal places improve serviceability accuracy.
drop_longdoubleMandatorylongitude of the drop address. Minimum 4 decimal places. Note: Higher decimal places improve serviceability accuracy.
store_idstringConditional MandatoryId of the store setup under Store Master in ClickPost. Mandatory if pickup_lat and pickup_long are not provided.
reference_numberstringMandatoryThe reference number for the API request. Up to 10 requests are allowed with the same reference number. Max allowed length is 50 characters. Allowed characters: alphanumerics and 3 special characters (-, _, .).
order_typeenumMandatoryThe order type for the particular shipment. Enum Values: 1. PREPAID : for prepaid order 2. COD : for cod order
pickup_pincodeintegerOptionalPin code of the pickup location.
drop_pincodeintegerOptionalPin code of the drop location.
invoice_valuefloatOptionalValue of the shipment as mentioned in the invoice. Cannot be negative
cod_valuefloatOptionalCash to be given to the carrier (currency to be determined by currency_code). Must be non-zero for COD orders, and zero for PREPAID orders. Cannot be negative
brand_etaintegerOptionalDelivery ETA of promise of the order in minutes. Used during rule evaluation and carrier filtering. Cannot be negative.

Sample Request Payload

{
  "pickup_lat": 12.342123,
  "pickup_long": 43.343234,
  "drop_lat": 54.64234232,
  "drop_long": 11.22424100,
  "store_id": null,
  "reference_number": "testref1234",
  "order_type": "COD",
  "pickup_pincode": 443280,
  "drop_pincode": 354320,
  "invoice_value": 200.45,
  "cod_value": 200.65,
  "brand_eta": 30
}

Response

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 ObjectThe result data of the API request.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
preference_arrayJSON arrayThe preference list of serviceable carrier partners. Ideally enterprise should keep a check on to this array only to see the recommended couriers.can be empty if no accounts found for recommendation
filters_ranJSON ObjectThe JSON object of all the filters that have been applied to derive the preference array. ClickPost includes this data in the response to inform the end user about the filters applied to generate the final preference array.cannot be null
request_idstringThe unique request identifier generated by ClickPost for each API request, used for tracing and debugging logs.cannot be null

preference_array object fields

Field NameData TypeDescriptionValue Constraints
cp_namestringThe name of the carrier partner.cannot be null
cp_idintegerCarrier Partner ID. This can be found on the dashboard or you can refer it here.cannot be null
account_codestringCarrier partner account name configured on the Clickpost dashboard.cannot be null
priorityintegerThe priority assigned to each carrier partner account for a store, as configured by the enterprise in ClickPost.cannot be null. If the store-to-carrier account configuration is not set up, the priority will be assigned randomly based on serviceability.

filters_ran fields

NOTE: <FILTER_ORDER> will be an integer sequence number starting from 1. Sequence can vary basis the configuration for recommendation engine. No hard checks should be applied on it.

Field NameData TypeDescriptionValue Constraints
<FILTER_ORDER>JSON ObjectDetails about filter applied and the result of the filter. For more details, check sample success response type.cannot be null

<FILTER_ORDER> fields

Field NameData TypeDescriptionValue Constraints
filter_namestringThe name of the filter applied. Possible values are: store_mapped_active_accounts, excluded_accounts, <STORE MAPPED RECOMMENDATION RULE NAME>, non_serviceable_accounts, no_riders_available_accounts, riders_available_accounts (This list may expand in future if additional rules to run the recommendation gets introduced)cannot be null
filter_resultJSON arrayThe list of carrier accounts filtered out for the given filter.can be empty

NOTE: The order of accounts in <STORE MAPPED RECOMMENDATION RULE NAME> filter represents their applied business priority.

filter_result object fields

Field NameData TypeDescriptionValue Constraints
cp_namestringThe name of the carrier partner.cannot be null
cp_idintegerCarrier partner ID. This can be found on the dashboard or you can refer it here.cannot be null
account_codestringCarrier partner account name configured on the Clickpost dashboard.cannot 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
4004024Store is not operational
500500Something went wrong in Clickpost server

Example Responses

Success Response

{
    "meta": {
        "success": true,
        "message": "Request is executed successfully",
        "status": 200
    },
    "result": {
        "preference_array": [
            {
                "cp_name": "Shadowfax Now Slot HLD",
                "cp_id": 220,
                "account_code": "Shadowfax_Now_HLD_1HR",
                "priority": 1
            },
            {
                "cp_name": "Adloggs HLD",
                "cp_id": 474,
                "account_code": "Adloggs_HLD_2HR",
                "priority": 2
            }
        ],
        "filters_ran": {
            "1": {
                "filter_name": "store_mapped_active_accounts",
                "filter_result": [
                    {
                        "cp_name": "Shadowfax Now Slot HLD",
                        "cp_id": 220,
                        "account_code": "Shadowfax_Now_HLD_1HR"
                    },
                    {
                        "cp_name": "Adloggs HLD",
                        "cp_id": 474,
                        "account_code": "Adloggs_HLD_2HR"
                    },
                    {
                        "cp_name": "Shiprocket HLD",
                        "cp_id": 513,
                        "account_code": "Shiprocket_HLD_1HR"
                    }
                ]
            },
            "2": {
                "filter_name": "excluded_accounts",
                "filter_result": []
            },
            "3": {
                "filter_name": "fixed_priority_rule_accounts",
                "filter_result": [
                    {
                        "cp_name": "Shadowfax Now Slot HLD",
                        "cp_id": 220,
                        "account_code": "Shadowfax_Now_HLD_1HR"
                    },
                    {
                        "cp_name": "Shiprocket HLD",
                        "cp_id": 513,
                        "account_code": "Shiprocket_HLD_1HR"
                    },
                    {
                        "cp_name": "Adloggs HLD",
                        "cp_id": 474,
                        "account_code": "Adloggs_HLD_2HR"
                    }
                ]
            },
            "4": {
                "filter_name": "non_serviceable_accounts",
                "filter_result": []
            },
            "5": {
                "filter_name": "no_riders_available_accounts",
                "filter_result": [
                    {
                        "cp_name": "Shiprocket HLD",
                        "cp_id": 513,
                        "account_code": "Shiprocket_HLD_1HR"
                    }
                ]
            },
            "6": {
                "filter_name": "riders_available_accounts",
                "filter_result": [
                    {
                        "cp_name": "Shadowfax Now Slot HLD",
                        "cp_id": 220,
                        "account_code": "Shadowfax_Now_HLD_1HR"
                    },
                    {
                        "cp_name": "Adloggs HLD",
                        "cp_id": 474,
                        "account_code": "Adloggs_HLD_2HR"
                    }
                ]
            }
        },
        "request_id": "150e1400-e29b-31d4-a716-446655440000"
    }
}

Error Response

{
  "meta": {
    "success": false,
    "message": "Invalid API key",
    "status": 4013
  },
  "result": null
}

Did this page help you?