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
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | ClickPost 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 Name | Data Type | Field | Description |
|---|---|---|---|
pickup_lat | double | Conditional Mandatory | latitude 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_long | double | Conditional Mandatory | longitude of the pickup address/store. Minimum 4 decimal places. Mandatory if store_idis not provided. Note: Higher decimal places improve serviceability accuracy. |
drop_lat | double | Mandatory | latitude of the drop address. Minimum 4 decimal places. Note: Higher decimal places improve serviceability accuracy. |
drop_long | double | Mandatory | longitude of the drop address. Minimum 4 decimal places. Note: Higher decimal places improve serviceability accuracy. |
store_id | string | Conditional Mandatory | Id of the store setup under Store Master in ClickPost. Mandatory if pickup_lat and pickup_long are not provided. |
reference_number | string | Mandatory | The 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_type | enum | Mandatory | The order type for the particular shipment. Enum Values: 1. PREPAID : for prepaid order 2. COD : for cod order |
pickup_pincode | integer | Optional | Pin code of the pickup location. |
drop_pincode | integer | Optional | Pin code of the drop location. |
| invoice_value | float | Optional | Value of the shipment as mentioned in the invoice. Cannot be negative |
| cod_value | float | Optional | Cash 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_eta | integer | Optional | Delivery 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 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 | The result data of the API request. | 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 |
|---|---|---|---|
preference_array | JSON array | The 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_ran | JSON Object | The 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_id | string | The unique request identifier generated by ClickPost for each API request, used for tracing and debugging logs. | cannot be null |
preference_array object fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
cp_name | string | The name of the carrier partner. | cannot be null |
cp_id | integer | Carrier Partner ID. This can be found on the dashboard or you can refer it here. | cannot be null |
account_code | string | Carrier partner account name configured on the Clickpost dashboard. | cannot be null |
priority | integer | The 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 Name | Data Type | Description | Value Constraints |
|---|---|---|---|
<FILTER_ORDER> | JSON Object | Details about filter applied and the result of the filter. For more details, check sample success response type. | cannot be null |
<FILTER_ORDER> fields
| Field Name | Data Type | Description | Value Constraints |
|---|---|---|---|
filter_name | string | The 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_result | JSON array | The 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 Name | Data Type | Description | Value Constraints |
|---|---|---|---|
cp_name | string | The name of the carrier partner. | cannot be null |
cp_id | integer | Carrier partner ID. This can be found on the dashboard or you can refer it here. | cannot be null |
account_code | string | Carrier partner account name configured on the Clickpost dashboard. | cannot 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 |
| 400 | 4024 | Store is not operational |
| 500 | 500 | Something 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
}Updated 13 days ago
Did this page help you?
