get https://www.clickpost.in/api/v4/create-order/
Given an AWB and a carrier partner ID, fetch details of a shipment placed with that AWB. Works for shipments created and transported within North America, Europe, Middle East and South-East Asia and all cross-border shipments. Especially useful when an async order is placed with the V4 API.
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
}
Important Links
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 couriers) URL to the generated commercial invoice of the order |
courier_partner_id | Integer | ID of the courier partner |
courier_name | String | Name of the courier |
sort_code | String/Null | Courier Partner Sort code. Certain couriers 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 |
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 courier partner. | 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 courier partner servers. | Need to retry after waiting for a while, or get in touch with Clickpost support or the courier partner 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 courier partner's API timed out. | Need to retry after waiting for a while, or get in touch with Clickpost support or the courier partner support. | No | "Courier Partner API timeout" |
351 | 200 | The account name of the courier partner 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 - Courier Partner ID in the courier_partner field.- Account name in the account_code field, and whether this account exists for this courier partner.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 courier partner 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 courier partner'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" |