Fetch Order Details: Rest of the World and Cross-Border

Overview

This API is used for getting details of an order placed with an international courier, given the waybill and the courier 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 all MPS (Multi-Piece Shipment) and SPS (Single Piece Shipment) orders

Geography

Shipments created and transported in
- North America
- Europe
- Middle East
- South East Asia
Cross-Border shipments: Shipments that are to be transported from India to any other country in the aforementioned regions, or vice versa

URL

GET <https://www.clickpost.in/api/v4/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 courier 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 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

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	The`order_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	The`priority` 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	The`delivery_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"