Fetch Order Details: India
Given an AWB and a carrier partner ID, fetch details of a shipment placed with that AWB. Works only for shipments created and transported within India.
Overview
This API is used for getting details of an order placed with a domestic (Indian) carrier, given the waybill and the carrier partner ID. This can be particularly useful for getting the response for an asynchronous order (which run in the background instead of in real-time).
Important Links
Usecase
This is a standard API which applies to MPS (Multi-Piece Shipments) and SPS (Single Piece Shipments) orders
Geography
This is a standard API which supports all shipments created and transported within India.
Path
GET <https://www.clickpost.in/api/v3/create-order/?username=test-enterprise&key=34be9be5-3de8-4223-ad14-d7391159b80e&awb=TESTAWB0001&cp_id=25
>
Query Parameters
Query Parameters to be passed directly in the URL.
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
username | String | Optional | Username of the enterprise | 100 | "test-enterprise" |
key | String | Mandatory | Unique license key provided by Clickpost for the enterprise, used for authentication | 100 | "34be9be5-3de8-4223-ad14-d7391159b80e" |
awb | String | Mandatory | AWB of the order to receive details for | 100 | "TESTAWB0001" |
cp_id | Integer | Mandatory | Partner ID of the carrier responsible for delivering the shipment | 25 |
Response
The response typically consists of the following fields. Keep in mind that additional fields can be present according to the requirement of the enterprise/courier.
Field Name | Data Type | Description |
---|---|---|
meta | Object | Metadata for the request, e.g. status code, error messages. |
result | Object | Actual result of the request |
order_id | Integer | Order ID of the shipment |
tracking_id | Integer | A special ID of the request used for tracking |
Response Meta
Field Name | Data Type | Description |
---|---|---|
status | Integer | Status code for the request (including but not limited to HTTP Status codes) |
message | String | Error/Success messages for the request |
success | Boolean | Whether the order was successfully created or not |
Response Result
Field Name | Data Type | Description |
---|---|---|
waybill | String | Waybill of the newly created order, or the one passed in the awb_number field (if any). This waybill is automatically registered for tracking in our database |
reference_number | String | Reference number of the order, sent in the payload. |
label | String/Null | URL to the generated label of the order. If labels are not needed, this stays null. |
commercial_invoice_url | String | (Appears for certain carriers) URL to the generated commercial invoice of the order |
courier_partner_id | Integer | Partner ID of the carrier |
courier_name | String | Name of the carrier |
sort_code | String/Null | Carrier Partner Sort code. Certain carriers use something called a sort code that can be passed to the shipping label for custom-built labels. Will return null if sort codes are not supported. |
security_key | String | UUID security key of the order that needs to be stored at the enterprise's end. |
children | Object | (Only for MPS responses) A list of item objects, with details of each item |
Sample Response
We can either get a 200 (OK) or a 400 (Bad Request) error as follows
{
"result": {
"waybill": "SKY0000006574",
"reference_number": "Test.SKYEXRVP.Order00002",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/SKYEXPRESS_RVP/2022-10-21/SKY0000006574.pdf",
"courier_partner_id": 325,
"courier_name": "SkyExpress",
"sort_code": null,
"order_id": 147175531,
"security_key": "4d36d09c-53b3-49f3-beb3-4eb8f884f941",
"tracking_id": 487501569
},
"meta": {
"status": 200,
"success": true,
"message": "Order Placed Successfully"
}
}
{
"meta": {
"status": 400,
"message": "Error Message",
"success": false
}
}
{
"result": {
"reference_number": "TestSolv00002",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/BLUEDART/2022-10-25/53433518935.pdf",
"waybill": "53433518935",
"children": [
{
"waybill": "53433518935-0001",
"item": {
"sku": "XYZ1",
"price": 200.0,
"images": "http://sample-file1.jpg,http://sample-file2.jpg",
"quantity": 13,
"description": "Cartoon Box 1",
"product_url": "<Product Page Url>",
"waybill": "53433518935-0001"
}
},
{
"waybill": "53433518935-0002",
"item": {
"sku": "XYZ2",
"price": 200.0,
"images": "http://sample-file1.jpg,http://sample-file2.jpg",
"quantity": 17,
"description": "Cartoon Box 1",
"product_url": "<Product Page Url>",
"waybill": "53433518935-0002"
}
}
],
"courier_partner_id": 000,
"courier_name": "Some International Courier",
"sort_code": "COK/KOO",
"order_id": "Order-123456",
"security_key": "3ee64ff7-be52-4e31-9ec5-21cf194cab03"
},
"meta": {
"status": 200,
"success": true,
"message": "Order Placed Successfully"
},
"order_id": 147885236,
"tracking_id": 491322827
}
Possible Error Codes
These are the list of possible error/status codes that can appear in the response metadata, and the actionables corresponding to each.
Meta Status Code | HTTP Status Code | Description | Actionable | Order Successful? | Status Message |
---|---|---|---|---|---|
102 | 200 | For async orders: The order has been recorded in Clickpost's database and is under processing. | Need to re-attempt Clickpost's order creation API to check if the order has been processed. | No | " |
200 | 200 | The order is successfully created | None | Yes | "Success" |
301 | 200 | The customer is sending an invalid/non-existent/inactive license key in the URL parameters | Need to re-attempt the order with a valid/registered/active license key. | No | "Authentication Failed: Invalid Token or API Key" |
302 | 200 | Either of the three things: - The customer is sending the courier_partner value as a string- The customer is sending a null value in the courier_partner field.- The partner ID being sent in courier_partner field does not exist. | Need to re-attempt the order with a valid integer value in the courier_partner field, and the value should exist in Clickpost's database. | No | "Invalid Courier Partner Id with Field courier_partner" |
303 | 200 | For async orders: The awb_number provided already exists and is registered by Clickpost | Need to re-attempt the order with a different awb_number value. | Yes | "Waybill already registered" |
307 | 200 | Theorder_type value is anything other than PREPAID , COD or EXCHANGE , or is null . | Need to re-attempt the order with the order_type as either PREPAID , COD or EXCHANGE . | No | "You have entered invalid Order Type" |
308 | 200 | Thepriority value is anything other than NORMAL or URGENT . | Need to re-attempt the order with the priority as either NORMAL or URGENT . | No | "You have entered invalid Order priority" |
309 | 200 | Thedelivery_type value is anything other than FORWARD or RVP . | Need to re-attempt the order with the delivery_type as either FORWARD or RVP . | No | "Invalid Delivery Type" |
310 | 200 | In case of RVP orders: This is due to either of the following - The rvp_reason field is missing- The rvp_reason length is more than 500 characters. | Need to re-attempt the RVP order with a non-null rvp_reason value within 500 characters. | No | "RVP reason is missing" or "RVP reason can't be more than 500 chars" |
311 | 200 | For RVP orders: The courier partner defined by the courier_partner field does not support RVP shipments, or is not an RVP courier. | Need to re-attempt the RVP order with a courier_partner value that supports RVP shipments. | No | "Invalid Courier Partner For RVP" |
312 | 200 | There is no item data in the payload (in the item field). | Need to retry the order with a non-empty items array. | No | "Items Data is missing from order details" |
313 | 200 | Either of the following: - The item data being sent in the items field is either a string or any other invalid format.- The items value is an array, but of anything other than objects.- The items value is an array of objects, but one or more mandatory fields are missing for one or more items. | Need to retry the order with proper items data, as an array of JSON objects. | No | "Invalid Format of items for Order data" |
314 | 200 | There is an issue with the order data being passed. | The error is captured in the status message. Retry the order after addressing the status message. | No | "Invalid Format of items for Order data: " |
315 | 200 | Either of the following: - For a PREPAID order, the cod_value is non-zero.- For a COD order, the cod_value is zero. | Need to retry the orders after: - (For PREPAID orders) setting the cod_value to zero.- (For COD orders) setting the cod_value to a non-zero number | No | "Invalid Cod Value" |
316 | 200 | There are no credentials for the courier partner of the account given in account_code , or the credentials are blank. | Need to re-attempt the order with a different account_code , or fill the credential fields in the dashboard and retry. | No | "You do not have credentials for the Courier Partner" |
319 | 200 | There is an issue in placing orders with the carrier. | The actual error generally pops up alongside the error message. In cases where the error message is vague, contact the support team. | No | "Error In Order Placing To Courier Partner: " |
320 | 200 | The enterprise has not subscribed for Clickpost's Order Creation Service. | Need to subscribe to the order creation service, then retry with all valid details and credentials. | No | "This service is not subscribed by you" |
321 | 200 | The awb provided in the awb_number field does not exist in Clickpost's database. | Need to provide a registered AWB, or remove the AWB field and try again. | No | "Awb Number Does not exist in system for courier partner" |
322 | 200 | There is an issue in the carrier servers. | Need to retry after waiting for a while, or get in touch with Clickpost support or the carrier's support. | No | "Internal Server Error In Courier Partners Server" |
323 | 200 | An order is already present in Clickpost's database with the same reference number as the one provided. | Need to re-attempt the order with a different reference number | Yes | "You have already placed this order" |
328 | 200 | Some mandatory field in the POST data might be missing. | Check for missing fields that are supposed to be there in the data and retry | No | "Invalid POST data" |
329 | 200 | The connection to the carrier's API timed out. | Need to retry after waiting for a while, or get in touch with Clickpost support or the carrier support. | No | "Courier Partner API timeout" |
351 | 200 | The account name of the carrier account given in the account_code field does not exist for the enterprise user. | The user needs to check either/all of the things below if they are correct - Enterprise license key in the URL params - Carrier ID in the courier_partner field.- Account name in the account_code field, and whether this account exists for this carrier.Re-attempt the order after correcting any of the incorrect details mentioned above. | No | "Clickpost Account: Does not exist" |
352 | 200 | There are multiple accounts of the same enterprise with the same carrier with the same name as the one in account_code field. | No | "Multiple account exists" | |
353 | 200 | The account mentioned in the account_code field is inactive. | Need to either enable the account on the dashboard from the enterprise's end, or use an active account. | No | "Clickpost Account: Inactive" |
354 | 200 | There is an unhandled error from the carrier's end. | The error is typically visible in the status message and can be fixed accordingly. In case of vague error messages, get in touch with the support team | No | "Unhandled error! Contact [email protected]" or the actual error |
355 | 200 | In certain couriers the vendor_code field is required. This error pops up whenever vendor_code is not passed in the payload | Need to pass the vendor_code field alongwith a registered vendor code. | No | "Vendor code not found" |
400 | 200 | There is an issue with the payload, or some invalid data is being sent in the request. | Need to fix the issues in the payload as mentioned in the status message. If "Bad Request" pops up, get in touch with the support team. | No | "Bad Request" or the actual error |
500 | 200 | There is an error in Clickpost's servers. | Need to wait a while and try again. If this error pops up even after multiple tries, get in touch with the support team. | No | "Oops! Internal server error in Clickpost" |
Updated over 1 year ago