Overview

By entering the shipment details along with the drop and pickup Pincode, e-enterprises can determine the optimal Carrier partner.

Our recommendation API helps you decide amongst your available Carrier Partners, the best, most efficient and dependable choice of delivery for any given package.
The enterprises can use the Recommendation API to trigger order creation/ order manifestation based on the API response
Get the preference array of the Carrier partner based on filters, Ordered List, Weightage feedback, and Load distribution. This can be configured in from the Clickpost Dashboard
Help document to configure recommendation rules on Clickpost dashboard : https://clickpost.freshdesk.com/a/solutions/articles/43000688518

Important Links

How to configure Recommendation Rules from Dashboard

Clickpost Dashboard > Home > Allocation > Allocation Rule

2866 — Clickpost Dashboard > Home > Allocation > Allocation Rule

Usecase

This is a standard API which applies to MPS (Multi-Piece Shipments) and SPS (Single Piece Shipments) orders

Geography

Shipments created and transported in
- North America
- Europe
- Middle East
- South East Asia
Cross-Border shipments: Shipments that are to be transported from India to any other country, or vice versa

❗️
NOTE
Serviceability supersedes Recommendation API. For example, if a particular Carrier Partner is not serviceable for a the Drop Pincode, then it will not feature in the preference array

URL

POST <https://www.clickpost.in/api/v2/recommendation/>

URL Parameters

Query Parameters to be passed directly in the URL.

Field Name	Data Type	Field	Description	Max Length	Example
`key`	String	Mandatory	Unique license key provided by Clickpost for the enterprise	100	"00000000-0000-0000-0000-000000000000"

Request Body

Pickup Info (`pickup_info`)

This mandatory object takes in the data for the warehouse/pickup location for the shipment.

Field Name	Data Type	Field	Description	Max Length	Example
`lat`	Float	Optional	Latitude of the pickup location		45.12211
`long`	Float	Optional	Longitude of the pickup location		88.12342
`city`	String	Mandatory	City of the pickup location	100	"Riyadh"
`name`	String	Mandatory	Contact name of the consignor of the shipment	100	"Tony Strak"
`address`	String	Mandatory	Address of the pickup location	500	"Strak Industry Logistics Park, Warehouse No 1002, Hyt, Riyadh, 14351"
`district`	String	Optional	District of the pickup location	100	"Chinatown"
`state`	String	Optional	State/province of the pickup location	100	"British Columbia"
`landmark`	String	Optional	Landmarks to help find the pickup location	500	"Near XYZ Towers"
`email`	String	Mandatory	Email of the pickup contact	50	"[email protected]"
`phone`	String	Mandatory	Contact number of the pickup contact	11	"9876543210"
`time`	String	Mandatory	Time of pickup for the order (to be provided in YYYY-MM-DDTHH:MM:SS format only)		2022-01-10T10:02:33
`postal_code`	String	Optional	Postal code of the pickup location	50	"Riyadh"
`country_code`	String	Mandatory	Alpha ISO-2 country code of the pickup location. Only "IN" is accepted as input.	2	"SA"
`delivery_instructions`	String	Optional	Delivery Instruction to be passed to the Carrier partner	100
`phone_code`	String	Mandatory	County code of the phone number	7	"+966"
`address_type`	String	Optional	Pickup address type	50	"Home"

Drop Info (`drop_info`)

This mandatory object takes in the data for the delivery/consignee location for the shipment.

Field Name	Data Type	Field	Description	Max Length	Example
`lat`	Float	Optional	Latitude of the drop location	6	45.12211
`long`	Float	Optional	Longitude of the drop location	6	88.12342
`name`	String	Mandatory	Contact name of the consignee of the shipment	100	"Mukesh Kumar"
`address`	String	Mandatory	Address of the drop location	500	"123, ABC Street"
`district`	String	Optional	District of the drop location	100	"Mumbai City"
`city`	String	Mandatory	City of the drop location	100	"Mumbai"
`state`	String	Mandatory	State/province of the drop location	100	"Maharashtra"
`landmark`	String	Optional	Landmarks to help find the drop location	500	"Near XYZ Towers"
`email`	String	Optional	Email of the drop contact	50	"[email protected]"
`phone`	String	Mandatory	Contact number of the drop contact	11	"9876543210"
`time`	String	Optional	Estimated time of drop for the order (to be provided in YYYY-MM-DDTHH:MM:SS format only)		2022-01-10T10:02:33
`postal_code`	String	Mandatory	Drop Postal code	100	"Tweeq"
`country_code`	String	Mandatory	Alpha ISO-2 country code of the drop location. Only "IN" is accepted as input.	2	"SA"
`address_type`	String	Optional	The address type of the drop location	100	"Home"

additional [additional parameters] [optional]

Field Name	Data Type	Field	Description	Example
`additional`	`JSON OBJECT`	Optional	The JSON Object of the additional parameter	{ "custom_fields": [{ "key": "ptl_or_ftl", "value": "PTL" }, { "key": "truck_size", "value": "14 feet" }
`key`	`string`	Optional	The enterprise defined field's key. This will come into picture, if enterprise want to set Enterprise defined allocation rules	"Customer_Type"
`value`	`string`	Optional	The enterprise defined field's value. This will come into picture, if enterprise want to set Enterprise defined allocation rules	"Prime Customer"

Shipment Details (`shipment_details`)

In the 'shipment_details' field, the details regarding all items, and important order details like payment type, order type, courier partner, etc. are added.

Field Name	Data Type	Field	Description	Max Length	Example
`items`	List[Object]	Mandatory	List of items to be delivered in the shipment. Details of the items explained below.
`height`	Float	Mandatory	Height of the overall package (in cms)		25.25
`width`	Float	Mandatory	Width of the overall package (in cms)		45.6
`length`	Float	Mandatory	Length of the overall package (in cms)		75.29
`weight`	Float	Mandatory	Weight of the package (in gms)		500.20
`reference_number`	String	Mandatory	Reference number of the order. Must be unique for every shipment, i.e. every call of this API.	100	"TestOrder00001"
`cod_value`	Float	Mandatory	Cash to be given to the courier (currency to be determined by `currency_code`). Must be non-zero for COD orders, and zero for PREPAID orders.		25.25
`order_id`	String	Optional	Identification string for the order	100	"TestOrderID00001"
`order_type`	String	Mandatory	Type of payment of the shipment. Can only take values "COD" or "PREPAID". `cod_value` must be non-zero for COD shipments and zero for PREPAID shipments.	10	"COD"/"PREPAID"
`delivery_type`	String	Mandatory	Type of delivery to be done. Can only take values "FORWARD" or "RVP".	10	"FORWARD"/"RVP"
`invoice_value`	Float	Mandatory	Value of the shipment as mentioned in the invoice.		256.29
`invoice_date`	String	Mandatory	Date of issuance of the invoice of the shipment. (`YYYY-MM-DD` format only)	100	2022-01-10
`invoice_number`	String	Mandatory	The Invoice number of the shipment.	100	"AB00001"

Item Level details (`items`)

The details for each item to be delivered is passed in the "items" field, in "shipment_details".

Field Name	Data Type	Field	Description	Max Length	Example
`cat`	String	Optional	Category of the item in question	50	Footwear
`description`	String	Mandatory	Brief description of the item	500	"Brown Cotton Socks - 1 pair"
`quantity`	Integer	Mandatory	Number of units of the item		5
`weight`	Float	Mandatory	Weight of each unit of the item		500
`price`	Float	Mandatory	Price of each unit of the item (currency to be decided by 'currency_code' field)		64.99
`manufacture_country_code`	String	Optional	Alpha-2 ISO Country code of manufacture of the item	2	"CA"
`manufacture_country`	String	Optional	Full country name of manufacture of the item	100	"Canada"
`sku`	String	Optional	Stock-keeping unit of the item	100	"SKU0001"

Response

meta [meta parameters]

Field Name	Data Type	Description	Example
`success`	`Boolean`	Indicates the success of the API request	`true`
`message`	`String`	The message from clickpost. In case of success it will be "SUCCESS". In case that there are no carrier partners that are servicing the pincodes it will be”Pin code not serviceable"	"SUCCESS"
`status`	HTTP Code	The HTTP response status code of the API request	200

result [result parameters]

Field Name	Data Type	Description	Example
`preference_array`	`array`	The preference list of eligible carrier partners	[ { "cp_name": "Delhivery", "cp_id": 4, "account_code": "Delhivery_Surface_B2C", "async": false, "account_id": 186908, "priority": 1, "scores_computation": { "scoring_params": { "PRICING": 57.11, "zone": "METRO" }, "total_score": 57.11 }, "shipping_charge": 57.11 }, { "cp_name": "XpressBees", "cp_id": 6, "account_code": "Xpressbees_Surface", "async": false, "account_id": 187017, "priority": 2, "scores_computation": { "scoring_params": { "PRICING": 59.97, "zone": "ROI" }, "total_score": 59.97 }, "shipping_charge": 59.97 }
`cp_name`	`String`	The name of the carrier partner	`Delhivery`
`cp_id`	`num`	Carrier Partner ID. This can be found on the dashboard or you can refer it to here	4
`account_code`	`string`	The name of the account configured inside of the carrier partner on the Clickpost dashboard	"Delhivery_Surface_B2C"
`async`	`Boolean`	Whether the carrier partner supports asynchronous order creation or not	false
`account_id`	`num`	The identifier for the particular account configured under the carrier partner	186908
`priority`	`num`	The priority of the carrier partner, this will be according to the Allocation rule set up by the enterprise on the Clickpost dashboard	1
`scores_computation`	`JSON Object`	The scoring of the carrier partner	{ "scoring_params": { "PRICING": 57.11, "zone": "METRO" }, "total_score": 57.11 }
`scoring_params`	`JSON Object`	The scoring parameters on which carrier partners are to be ranked	{ "PRICING": 57.11, "zone": "METRO" }
`PRICING`	`num`	The pricing of the carrier partner	57.11
`zone`	`String`	The zone which has been mapped with pincodes on the clickpost dashboard under the courier integration section.This can be configured in the Pricing section in courier partner account configuration section. (Settings>Courier>Integrations>Accounts> Configuration > Pricing)	"METRO"
`total_score`	`num`	The total score for the particular carrier partner	57.11
`shipping_charge`	`num`	The total shipping charge that the carrier partner will charge for the particular shipment	57.11
`filters_ran`	`JSON Object`	The JSON object of all the filters that have applied	"filters_ran": { "1_active_accounts_filter": [], "2_serviceable_accounts_filter":[], "2_1_serviceable_oda_accounts_filter": [], 3_clickpost_define_and_custom_filters_accounts: [], 4_ordered_list_account_names_filters_applied: false, ordered_list_filter_accounts: [] }
`1_active_accounts_filter`	`array`	The list of active carriers that are there on Clickpost account	[ "Delhivery_Surface_Heavy(Delhivery(186909))", "Delhivery_Surface_B2C(Delhivery(186908))", "Delhivery_Express_B2C(Delhivery(186907))", "Delhivery_Surface_Bulk(Delhivery(186915))", "Porter_criticallog(CriticalLog(187713))", "Xpressbees_Surface(XpressBees(187017))", "Xpressbees_Express(XpressBees(187306))", "EcomExpress_Surface(EcomExpress(187019))", "Ekart_Surface(Ekart Logistics(187018))" ]
`2_serviceable_accounts_filter`	`array`	The list of serviceable carrier partners for the particular pickup and drop pincode	[ "Delhivery_Surface_Bulk(Delhivery(186915))", "Xpressbees_Surface(XpressBees(187017))", "Delhivery_Express_B2C(Delhivery(186907))", "Delhivery_Surface_B2C(Delhivery(186908))", "Delhivery_Surface_Heavy(Delhivery(186909))" ]
`2_1_serviceable_oda_accounts_filter`	`array`

Fetch Recommended Carriers: Rest of the World and Cross Border

Overview

Important Links

How to configure Recommendation Rules from Dashboard

Usecase

Geography

❗️
NOTE

URL

URL Parameters

Request Body

Pickup Info (`pickup_info`)

Drop Info (`drop_info`)

Shipment Details (`shipment_details`)

Item Level details (`items`)

Response

Overview

Important Links

How to configure Recommendation Rules from Dashboard

Usecase

Geography

❗️NOTE

URL

URL Parameters

Request Body

Pickup Info (pickup_info)

Drop Info (drop_info)

Shipment Details (shipment_details)

Item Level details (items)

Response

❗️
NOTE

Pickup Info (`pickup_info`)

Drop Info (`drop_info`)

Shipment Details (`shipment_details`)

Item Level details (`items`)