Order Details via Polling

This API is used to fetch the current status and details of the Order Reallocation (Carrier Hopping) flow.

Overview & Usage

This API allows clients to fetch the current status of order reallocation requests initiated via the api/v1/quickcom/reallocation endpoint. It provides visibility into shipment creation progress and carrier allocation/reallocation outcomes throughout the reallocation (carrier hopping) workflow.

Clients should poll this API at regular intervals (recommended every 30 seconds) until a terminal status is reached, making it suitable for systems where webhook consumption is not enabled or as a fallback mechanism for status tracking.

Allowed HTTP Methods

GET

URL

<baseURL>/api/v2/quickcom/fetch_order_details

baseURL - https://hld.clickpost.in

URL Query Parameters

ParameterTypeRequiredDescription
keystringYesClickPost API key
original_reference_numberstringYesUnique reference number of the order, as sent in the Reallocation API payload.

Sample API cURL

curl --location --request GET '<baseURL>/api/v2/quickcom/fetch_order_details?key=<API_KEY>&original_reference_number=TEST123'

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
original_reference_numberstringUnique reference number of the order, as provided in the Reallocation API payload.cannot be null
statusstringIndicates the status of the order placed using reallocation API.cannot be null; refer to the list below
status_codeintegercode of the statuscannot be null; refer to the list below
order_detailsJSON ObjectDetails of the finalized carrier shipment or intermediary allocated carrier shipment.will be null, if status is NOT terminal; refer to the status list below
request_idstringThe unique request identifier generated by ClickPost for each API request, used for tracing and debugging logs.cannot be null

status and status_code list:

StatusStatus CodeDescriptionIs Terminal Status
SHIPMENT_CREATION_INITIATED1Initial state when carrier reallocation process has started but no successful shipment manifestation has occurred yet. No shipment data available.No
SHIPMENT_CREATION_SUCCESSFUL2Reallocation completed successfully with a carrier allocated and shipment created. Shipment data is available. Final success state.Yes
SHIPMENT_CREATION_FAILED3Reallocation process timed out without any successful shipment manifestation, or the last manifestation attempt resulted in a non-success status. No shipment data available. Terminal failure state.Yes
CARRIER_ALLOCATED4Carrier has been allocated and an active manifestation exists, waiting for rider to be allocated and/or order to be picked up within the reallocation time window. Shipment data is available. Reallocation is still in progress.No
CARRIER_ALLOCATED_PROVISIONALLY5Carrier allocated but not confirmed that a rider will be assigned and/or order will be picked up by the allocated carrier. This occurs when either reallocation timed out but last attempt succeeded, or manifestation was skipped due to cancellation errors from the carrier side. Shipment data available but enterprise should manage this now at their end. Terminal unconfirmed state.Yes
REALLOCATION_ABORTED6The reallocation flow has been aborted and terminated. The latest AWB cancellation was attempted as part of this termination; check the order_details.awb_cancelled boolean flag to determine whether the cancellation succeeded or failed. This is a terminal state.Yes
REALLOCATION_PAUSED7Sent when reallocation is paused because order creation is not responding, or a previous order is still being cancelled. The brand is informed that courier assignment is on hold. Reallocation can continue once order creation is working again. If the pause reaches 1 hour, reallocation is stopped.
(Note: No active AWB present in this state)
No
REALLOCATION_UNEXPECTEDLY_ABORTED8Sent when reallocation is stopped before a courier is confirmed. This happens when order creation fails and cannot be retried, or when reallocation has already been paused for 1 hour. No further courier attempts are made.
(Note: No active AWB present in this state)
Yes

order_details object fields

Field NameData TypeDescriptionValue Constraints
awbstringAWB/Waybill of the successfully created order. This AWB is automatically registered for tracking in the ClickPost system.cannot be null
reference_numberstringA new reference number generated from the original reference number by adding a sequential numeric prefix or suffix (e.g., “1-”, “2-”, “-1”, “-2”).cannot be null
shipping_labelstringURL to the generated shipping label of the order. If labels are not needed, this stays null.can be null
cp_idintegerID of the courier partner. This can be found on the dashboard or you can refer it here.cannot be null
cp_namestringThe name of the courier partner.cannot be null
account_codestringCourier partner account name configured on the Clickpost dashboard.cannot be null
tracking_idbigint / longA special ID of the order/shipment used for tracking.cannot be null
security_keystringUUID security key of the order that needs to be stored at the enterprise's end.cannot be null
awb_cancelledbooleanIndicates whether the latest AWB (if present) was cancelled successfully after the reallocation flow was aborted.can 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
500500Something went wrong in Clickpost server

Example Responses

Sample Success Status Responses

{
    "result": {
        "original_reference_number": "123456789",
        "status": "SHIPMENT_CREATION_INITIATED",
        "status_code": 1,
        "order_details": null,
        "request_id": "12f1075b-3bc7-48dd-b8fd-a41dfe41550e"
    },
    "meta": {
        "status": 200,
        "success": true,
        "message": "Request is executed successfully"
    }
}
{
    "result": {
        "original_reference_number": "123456789",
        "status": "SHIPMENT_CREATION_SUCCESSFUL",
        "status_code": 2,
        "order_details": {
            "awb": "100100034234",
            "reference_number": "123456789-2",
            "shipping_label": "https://clickpost-label.s3.amazonaws.com/1764322758.pdf",
            "cp_id": 596,
            "cp_name": "PicoXpress HLD",
            "account_code": "test",
            "tracking_id": 11243667,
            "security_key": "216c3d4e-ac10-403b-aea9-55d853f08d8d",
            "awb_cancelled": null
        },
        "request_id": "65f1075b-4bc7-48dd-b8fd-a41dfe41250c"
    },
    "meta": {
        "status": 200,
        "success": true,
        "message": "Request is executed successfully"
    }
}
{
    "result": {
        "original_reference_number": "123456789",
        "status": "SHIPMENT_CREATION_FAILED",
        "status_code": 3,
        "order_details": null,
        "request_id": "35f1075b-3bc7-48dd-a8fd-a41dfe41531a"
    },
    "meta": {
        "status": 200,
        "success": true,
        "message": "Request is executed successfully"
    }
}
{
    "result": {
        "original_reference_number": "123456789",
        "status": "CARRIER_ALLOCATED",
        "status_code": 4,
        "order_details": {
            "awb": "TY423223242",
            "reference_number": "3-123456789",
            "shipping_label": "https://clickpost-label.s3.amazonaws.com/TY423223242.pdf",
            "cp_id": 364,
            "cp_name": "Porter HLD",
            "account_code": "test",
            "tracking_id": 11243557,
            "security_key": "346c3d4e-ac10-203b-bea9-33d853f08d85",
            "awb_cancelled": null
        },
        "request_id": "15f1085b-4bc7-48dd-b8fd-a41dfe44350d"
    },
    "meta": {
        "status": 200,
        "success": true,
        "message": "Request is executed successfully"
    }
}
{
    "result": {
        "original_reference_number": "123456789",
        "status": "CARRIER_ALLOCATED_PROVISIONALLY",
        "status_code": 5,
        "order_details": {
            "awb": "SFX2387192",
            "reference_number": "123456789-4",
            "shipping_label": "https://clickpost-label.s3.amazonaws.com/SFX2387192.pdf",
            "cp_id": 220,
            "cp_name": "Shadowfax Now Slot HLD",
            "account_code": "test",
            "tracking_id": 11243214,
            "security_key": "676c3d4e-ac10-203b-bea9-33d853f08d14",
            "awb_cancelled": null
        },
        "request_id": "15f1085b-4bc7-48dd-b8fd-a41dfe44350d"
    },
    "meta": {
        "status": 200,
        "success": true,
        "message": "Request is executed successfully"
    }
}
{
    "result": {
        "original_reference_number": "123456789",
        "status": "REALLOCATION_ABORTED",
        "status_code": 6,
        "order_details": {
            "awb": "100100034234",
            "reference_number": "123456789-2",
            "shipping_label": "https://clickpost-label.s3.amazonaws.com/1764322758.pdf",
            "cp_id": 596,
            "cp_name": "PicoXpress HLD",
            "account_code": "test",
            "tracking_id": 11243667,
            "security_key": "216c3d4e-ac10-403b-aea9-55d853f08d8d",
            "awb_cancelled": false
        },
        "request_id": "65f1075b-4bc7-48dd-b8fd-a41dfe41250c"
    },
    "meta": {
        "status": 200,
        "success": true,
        "message": "Request is executed successfully"
    }
}
{
    "result": {
        "original_reference_number": "123456789",
        "status": "REALLOCATION_ABORTED",
        "status_code": 6,
        "order_details": null,
        "request_id": "35f1075b-3bc7-48dd-a8fd-a41dfe41531a"
    },
    "meta": {
        "status": 200,
        "success": true,
        "message": "Request is executed successfully"
    }
}

Sample Bad Request Response

{
    "result": "No order details found for original reference number: 231241241",
    "meta": {
        "status": 4002,
        "success": false,
        "message": "Request for invalid entity"
    }
}

Did this page help you?