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

ParameterTypeRequiredDescription
keystringYesClickPost 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_lat and pickup_info.pickup_long or additional.hld_store_id must be provided.
  • drop_info.drop_lat and drop_info.drop_long must be provided.
  • only FORWARD delivery type is supported for the reallocation process in the following field: shipment_details.delivery_type
  • only COD and PREPAID order type is supported for the reallocation process in the following field: shipment_details.order_type
  • additional.brand_eta is 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 to 0.
{
    "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 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
original_reference_numberstringSame reference number as provided in the request payload.cannot be null
order_labelstringURL to the generated label of the order without assigned courier details. If label is not needed, this stays null.can be null
request_idlongThe 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 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

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

Did this page help you?