Reallocation (Carrier Hopping)
Overview
Reallocation is designed as an asynchronous workflow that repeatedly attempts courier assignment until either a courier is successfully allocated or the configured timeout is reached. This non-blocking process enables multiple retry cycles across different courier partners, significantly reducing the number of orders that fail allocation when relying on a single courier and improving overall success rates for HLD orders.
Prerequisites
-
The enterprise must be subscribed to the service.
-
The Store Master configuration must be present in ClickPost.
-
Store-Carrier mappings for each store must be present in ClickPost.
-
To select carriers for the reallocation process, carrier recommendation rules must be configured in ClickPost.
-
Configure the timeout values:
- Reallocation Timeout (default: 60 mins)
- Rider Allocation Timeout (default: 10 mins)
- Rider Reached Pickup Timeout (default: 0 mins)
- Order Pickup Timeout (default: 10 mins)
- Reallocation Post Timeout Action -
- TERMINATE
- CREATE_ORDER_AND_TERMINATE (default)
-
To know the status of the reallocation process, enterprise can poll the Order Details via Polling API at fixed intervals of time or enable the Order Details via Webhook to get the status updates in real time. Refer further sections to get more details.
Note: Contact the ClickPost team for assistance with setup and service enablement.
Important Note
The reference_number passed in this API will be considered as original reference number during the entire reallocation process. So original_reference_number will be an identifier using which enterprise can get complete visibility of that specific order.
If the requested store is not operational (i.e., outside its configured operating hours), the API will return an error response.
Sample Order Label PDF Snapshot (Size: A4)
Allowed HTTP Methods
POST
URL
<baseURL>/api/v1/quickcom/reallocation
baseURL - https://hld.clickpost.in
Headers
{
"Content-Type": "application/json"
}URL Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | ClickPost API key |
Sample Request Payload
NOTE:
Request payload will be same as Order Creation V3 API payload excluding following fields from the payload, as Reallocation system of ClickPost will find out the best carrier to allocate your order, hence these fields related to carrier is not required to pass in the payload.shipment_details.courier_partner,shipment_details.account_code,additional.async
Note for Mandatory and Optional fields:
- Either
pickup_info.pickup_latandpickup_info.pickup_longoradditional.hld_store_idmust be provided. drop_info.drop_latanddrop_info.drop_longmust be provided.- only
FORWARDdelivery type is supported for the reallocation process in the following field:shipment_details.delivery_type - only
CODandPREPAIDorder type is supported for the reallocation process in the following field:shipment_details.order_type additional.brand_etais an optional field. The promised delivery ETA for the order, in minutes. This value is used during recommendation rule evaluation and carrier filtering. If provided, the value must be greater than or equal to0.
{
"pickup_info": {
"pickup_state": "Maharashtra",
"pickup_address": "Indiranagar ",
"email": "[email protected]",
"pickup_time": "2025-03-01T19:00:00Z",
"pickup_pincode": "400077",
"pickup_city": "Mumbai",
"tin": "120349483",
"pickup_name": "TS Surface",
"pickup_country": "India",
"pickup_phone": "9917344496",
"pickup_lat": 10.01,
"pickup_long": 10,
"pickup_organisation": "Nykaa",
"pickup_district": "Mumbai",
"pickup_landmark": "Near XYZ Towers",
"pickup_address_type": "RESIDENTIAL"
},
"drop_info": {
"drop_address": "F-68 third floor kalkaji New Delhi ",
"drop_phone": "9717732407",
"drop_country": "IN",
"drop_state": "DELHI",
"drop_pincode": "400024",
"drop_city": "Delhi",
"drop_name": "Prashant",
"drop_email": "[email protected]",
"drop_lat": 10.01,
"drop_long": 10,
"drop_organisation": "Nykaa",
"drop_district": "Delhi",
"drop_landmark": "Near XYZ Towers",
"drop_start_time": "2025-03-05T10:02:33+0530",
"drop_end_time": "2025-03-05T12:02:33+0530",
"drop_address_type": "RESIDENTIAL",
"drop_vendor_code": "",
"location_type": "What3Words",
"location_value": "stickler.leaky.workers"
},
"shipment_details": {
"order_type": "COD",
"invoice_value": 200,
"invoice_number": "INV123",
"invoice_date": "2025-02-27",
"reference_number": "testref123",
"length": 10,
"breadth": 10,
"weight": 100,
"height": 12,
"cod_value": 200.45,
"order_id": "test123",
"delivery_type": "FORWARD",
"items": [
{
"product_url": "<Product Page Url>",
"price": 200.78,
"description": "item1",
"quantity": 1,
"weight": 500.25,
"sku": "XYZ1",
"final_amount_paid": "200.00",
"store_credits_used": "50.50",
"product_id": "4817825955902",
"variant_id": "32783884976190",
"additional": {
"length": 10,
"height": 10,
"breadth": 10,
"weight": 100,
"images": "http://sample-file1.jpg,http://sample-file2.jpg",
"return_days": 2,
"cat": "Footwear",
"manufacture_country_code": "IN",
"manufacture_country": "India",
"exchange_days": 5,
"color": "dark blue",
"sub_category": "T-Shirt",
"size": "XL",
"brand": "Puma",
"special_instructions": "Handle with care",
"imei": "12345678910111",
"ean": "EAN111111",
"product_url": "https://www.clickpost.ai",
"return_reason": "Some test reason"
}
}
]
},
"additional": {
"hld_store_id": "BLR_STORE_1",
"brand_eta": 20,
"return_info": {
"pincode": "110019",
"address": "Test Address top floor kalkaji NewDelhi ",
"state": "DELHI",
"phone": "8080808080",
"name": "Deepanshu",
"city": "DELHI",
"country": "IN",
"lat": 25.1414664,
"long": 55.255369,
"district": "Delhi",
"landmark": "Near XYZ Towers",
"email": "[email protected]"
},
"gst_number": "21313",
"channel_name": "Testchannel",
"order_date": "2023-11-05T00:00:00+00:00",
"enable_whatsapp": false,
"is_fragile": true,
"is_dangerous": true,
"zone": "XYZ Locality",
"max_edd": 10,
"min_edd": 5,
"invoice_base_64": "XYZ",
"is_multi_seller": false,
"otp_flag": true,
"otps": {
"pickup_otp": "1234",
"delivery_otp": "1234",
"return_otp": "1234"
},
"vendor_code": "",
"store_code": "abc",
"user_defined_field_array": [
{
"name": "udf_1",
"type": "String",
"value": ""
},
{
"name": "udf_2",
"type": "String",
"value": ""
},
{
"name": "udf_3",
"type": "String",
"value": ""
},
{
"name": "udf_4",
"type": "String",
"value": ""
}
],
"estimated_delivery_date": "2023-12-05"
},
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100.55,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"gst_tax_base": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100,
"invoice_number": "12345",
"invoice_date": "2024-01-22",
"invoice_value": 1000,
"seller_name": "",
"seller_address": "",
"seller_state": "",
"seller_pincode": ""
}
}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 |
|---|---|---|---|
original_reference_number | string | Same reference number as provided in the request payload. | cannot be null |
order_label | string | URL to the generated label of the order without assigned courier details. If label is not needed, this stays null. | can be null |
request_id | long | The unique request identifier generated by ClickPost for each successful API request, used for tracing and debugging logs. | 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
Sample Success Response
{
"meta": {
"success": true,
"message": "Request is executed successfully",
"status": 200
},
"result": {
"original_reference_number": "testref123",
"order_label": "https://pyck-res-bucket.s3.amazonaws.com:443/SFXNOWSLOT/SFXN0000006574.pdf",
"request_id": 1234
}
}Sample Error Response 1
{
"meta": {
"success": false,
"message": "Invalid request json",
"status": 4001
},
"result": "reference_number already exists"
}Sample Error Response 2
{
"meta": {
"success": false,
"message": "Invalid request json",
"status": 4001
},
"result": "pickup_info.pickup_address: Required field missing, pickup_info.pickup_time: Required field missing"
}Updated 13 days ago
