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
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | ClickPost API key |
original_reference_number | string | Yes | Unique 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 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 | Unique reference number of the order, as provided in the Reallocation API payload. | cannot be null |
status | string | Indicates the status of the order placed using reallocation API. | cannot be null; refer to the list below |
status_code | integer | code of the status | cannot be null; refer to the list below |
order_details | JSON Object | Details 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_id | string | The unique request identifier generated by ClickPost for each API request, used for tracing and debugging logs. | cannot be null |
status and status_code list:
| Status | Status Code | Description | Is Terminal Status |
|---|---|---|---|
| SHIPMENT_CREATION_INITIATED | 1 | Initial state when carrier reallocation process has started but no successful shipment manifestation has occurred yet. No shipment data available. | No |
| SHIPMENT_CREATION_SUCCESSFUL | 2 | Reallocation completed successfully with a carrier allocated and shipment created. Shipment data is available. Final success state. | Yes |
| SHIPMENT_CREATION_FAILED | 3 | Reallocation 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_ALLOCATED | 4 | Carrier 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_PROVISIONALLY | 5 | Carrier 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_ABORTED | 6 | The 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_PAUSED | 7 | Sent 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_ABORTED | 8 | Sent 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 Name | Data Type | Description | Value Constraints |
|---|---|---|---|
awb | string | AWB/Waybill of the successfully created order. This AWB is automatically registered for tracking in the ClickPost system. | cannot be null |
reference_number | string | A 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_label | string | URL to the generated shipping label of the order. If labels are not needed, this stays null. | can be null |
cp_id | integer | ID of the courier partner. This can be found on the dashboard or you can refer it here. | cannot be null |
cp_name | string | The name of the courier partner. | cannot be null |
account_code | string | Courier partner account name configured on the Clickpost dashboard. | cannot be null |
tracking_id | bigint / long | A special ID of the order/shipment used for tracking. | cannot be null |
security_key | string | UUID security key of the order that needs to be stored at the enterprise's end. | cannot be null |
awb_cancelled | boolean | Indicates whether the latest AWB (if present) was cancelled successfully after the reallocation flow was aborted. | can 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 |
| 500 | 500 | Something 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"
}
}Updated 11 days ago
