Register shipment for tracking: V3

Overview

Register an AWB for tracking updates with Clickpost, given the AWB number, carrier partner ID, shipment information, pick-up and drop information and additional details as input. This applies to shipments created and transported within North America, Europe, the Middle East, South-East Asia, and cross-border shipments.

Usecase

This is a standard API that applies to all MPS (Multi-Piece Shipment) and SPS (Single Piece Shipment) orders

Geography

This API is supported globally

Path

POST <https://www.clickpost.in/api/v3/tracking/awb-register/?key=>

Query Parameters

Field Name	Data Type	Field	Description	Max Length	Example
`key`	String	Mandatory	Unique license key for the enterprise user provided by Clickpost	100	"34be9be5-3de8-4223-ad14-000000000000"

Body Payload

Payload encapsulates details regarding the AWB to be registered, and its details

Field Name	Data Type	Field	Description	Max Length	Example
`waybill`	String	Mandatory	AWB to be registered	100	"TESTAWB00001"
`courier_partner`	Integer	Mandatory	Each carrier partner has a unique identifier (Integer value) in the Clickpost system, which will be used to identify the courier partner and track the shipment. List: http://track.clickpost.in/courier_partner		215
`account_code`	String	Mandatory	Courier partner account name configured on the Clickpost dashboard	100	"test_account"
`shipment_info`	Object	Optional	Details of the shipment to be registered
`pickup_info`	Object	Optional	Details for pickup of the shipment
`drop_info`	Object	Optional	Details for delivery of the shipment
`additional`	Object	Optional	Additional optional fields

Pickup Info (pickup_info)

This object takes in the data for the warehouse/pickup location for the shipment.

Field Name	Data Type	Field	Description	Max Length	Example
`lat`	Float	Optional	Latitude of the pickup location		45.12211
`long`	Float	Optional	Longitude of the pickup location		88.12342
`name`	String	Optional	Contact name of the consignor of the shipment	100	"John Smith"
`address`	String	Optional	Address of the pickup location	500	"123, ABC Street"
`district`	String	Optional	District of the pickup location	100	"Nadia"
`city`	String	Optional	City of the pickup location	100	"Frankfort"
`state`	String	Optional	State/province of the pickup location	100	"Ohio"
`landmark`	String	Optional	Landmarks to help find the pickup location	500	"Near XYZ Towers"
`email`	String	Optional	Email of the pickup contact	50	"[email protected]"
`phone`	String	Optional	Contact number of the pickup contact	11	"9876543210"
`phone_code`	String	Optional	Country calling codes or country dial-in codes are telephone number prefixes for reaching telephone subscribers in the networks of the member countries or regions of the International Telecommunication Union (ITU)	5	"+91"
`time`	String	Optional	Time of pickup for the order (to be provided in YYYY-MM-DDTHH:MM:SS format only)		2022-01-10T10:02:33
`postal_code`	String	Optional	Postal code of the pickup location	10	"L4YG6C"
`country_code`	String	Optional	Alpha ISO-2 country code of the pickup location	2	"CA"

Drop Info (drop_info)

This object takes in the data for the delivery/consignee location for the shipment.

Field Name	Data Type	Field	Description	Max Length	Example
`lat`	Float	Optional	Latitude of the drop location		45.12211
`long`	Float	Optional	Longitude of the drop location		88.12342
`name`	String	Optional	Contact name of the consignee of the shipment	100	"John Smith"
`address`	String	Optional	Address of the drop location	500	"123, ABC Street"
`district`	String	Optional	District of the drop location	100	"Nadia"
`city`	String	Optional	City of the drop location	100	"Frankfort"
`state`	String	Optional	State/province of the drop location	100	"Ohio"
`landmark`	String	Optional	Landmarks to help find the drop location	500	"Near XYZ Towers"
`email`	String	Optional	Email of the drop contact	50	"[email protected]"
`phone`	String	Optional	Contact number of the drop contact	11	"9876543210"
`time`	String	Optional	Estimated time of drop for the order (to be provided in YYYY-MM-DDTHH:MM:SS format only)		2022-01-10T10:02:33
`postal_code`	String	Optional	Postal code of the drop location	10	"L4YG6C"
`country_code`	String	Optional	Alpha ISO-2 country code of the drop location	2	"CA"

Additional Fields (additional)

In the "additional" object optional fields can be passed which may be used by the carrier partner, or give additional details for the order.

Field Name	Data Type	Field	Description	Max Length	Example
`order_date`	String	Optional	Date of placing the order (in YYYY-MM-DD format)	50	"2022-10-01"
`ship_date`	String	Optional	Date of shipping the order (in YYYY-MM-DD format)	50	"2022-10-01"
`language_code`	String	Optional	ISO 639-2 Code	2	"eng"
`min_edd`	Integer	Optional	Minimum committed estimated delivery duration (in days) of the shipment		5
`max_edd`	Integer	Optional	Maximum committed estimated delivery duration (in days) of the shipment		5

Shipment Details (shipment_details)

In the 'shipment_details' field, the details regarding all items, and important order details like payment type, order type, carrier partner, etc. are added.

Field Name	Data Type	Field	Description	Max Length	Example
`items`	List[Object]	Optional	List of items to be delivered in the shipment. Details of the items explained below.
`height`	Float	Optional	Height of the overall package (in cms)		25.25
`breadth`	Float	Optional	Width of the overall package (in cms)		45.6
`length`	Float	Optional	Length of the overall package (in cms)		75.29
`weight`	Float	Optional	Weight of the package (in gms)		500.20
`reference_number`	String	Optional	Reference number of the order. Must be unique for every shipment, i.e. every call of this API.	100	"TestOrder00001"
`cod_value`	Float	Optional	Cash to be given to the carrier (currency to be determined by `currency_code`). Must be non-zero for COD orders, and zero for PREPAID orders.		25.25
`order_id`	String	Optional	ID of the order	100	"TestOrderID00001"
`order_type`	String	Optional	Type of payment of the shipment. Can only take values "COD" or "PREPAID". `cod_value` must be non-zero for COD shipments and zero for PREPAID shipments.	10	"COD"/"PREPAID"
`invoice_value`	Float	Optional	Value of the shipment as mentioned in the invoice.		256.29
`invoice_date`	String	Optional	Date of issuance of the invoice of the shipment. (`YYYY-MM-DD` format only)	100	2022-01-10

Item Level details (items)

The details for each item to be delivered is passed in the "items" field, in "shipment_details".

Field Name	Data Type	Field	Description	Max Length	Example
`cat`	String	Optional	Category of the item in question	50	Footwear
`description`	String	Optional	Brief description of the item	500	"Brown Cotton Socks - 1 pair"
`quantity`	Integer	Optional	Number of units of the item		5
`weight`	Float	Optional	Weight of each unit of the item		500
`price`	Float	Optional	Price of each unit of the item (currency to be decided by 'currency_code' field)		64.99
`manufacture_country_code`	String	Optional	Alpha-2 ISO Country code of manufacture of the item	2	"CA"
`manufacture_country`	String	Optional	Full country name of manufacture of the item	100	"Canada"
`sku`	String	Optional	Stock-keeping unit of the item	100	"SKU0001"
`return_days`	Integer	Optional	Number of days within which the item can be returned		5
`exchange_days`	Integer	Optional	Number of days within which the item can be exchanged		5
`product_url`	String	Optional	URL for the product. If there are multiple URLs, they can be sent as a single string with comma-separated values.	1000	"http://link1.to.product, http://link2.to.product"
`images`	String	Optional	URL for the image(s) of the product. If there are multiple URLs, they can be sent as a single string with comma-separated values.	1000	"http://link.to.product.image1, http://link.to.product.image2"
`extras`	Dict	Optional	Any custom data, in the key-value pair format, that you wish to send along with the shipment item info. Eg: Brand data, HSN Code etc	1000	{"brand":"Tesla"}

Response

Field Name	Data Type	Description
`meta`	Object	Metadata for the result, e.g. status code, error messages.
`result`	Object	Actual result of the request

Response Meta

Field Name	Data Type	Description
`status`	Integer	Status code of the response (including, but not limited to HTTP Status codes)
`message`	String	Error message (if any errors) for the request.
`success`	Boolean	Whether the request is successful or not.

Response Result

Field Name	Data Type	Description
`tracking_id`	Integer	Tracking ID of the newly registered waybill stored in our database.
`security_key`	String	UUID string for the security key of the order

Sample Request

{
   "waybill":"ABCDEFGHIJKL0001",
   "courier_partner":246,
   "account_code":"test.skip.mps.rvp",
   "shipment_info":{
      "order_type":"COD",
      "invoice_value":"12345",
      "cod_amount":"1000",
      "currency_code":"SAR",
      "reference_number":"123XYZ",
      "order_id":"order_id of the shipment",
      "length":10,
      "height":10,
      "weight":10,
      "breadth":10,
      "items":[
         {
            "sku":"XYZ1",
            "description":"item1",
            "quantity":1,
            "price":200,
            "images":"<Image URL>",
            "return_days":2,
            "length":10,
            "height":10,
            "breadth":10,
            "weight":100,
            "extra":{
               "brand":"Tesla",
               "cat":"Electronic Vehicle"
            }
         }
      ]
   },
   "pickup_info":{
      "name":"DEFG",
      "email":"[email protected]",
      "phone_code":"966",
      "phone":"1234567890",
      "address":"Some Address",
      "postal_code":"JK0701",
      "city":"Riyadh",
      "district":"XYZ",
      "state":"Al-Riyadh",
      "country_code":"SA",
      "lat":10.01,
      "long":10.2
   },
   "drop_info":{
      "name":"ABCD",
      "email":"[email protected]",
      "phone_code":"966",
      "phone":"9876443210",
      "address":"ABCD TOWERS",
      "postal_code":"JK0703",
      "city":"JK0703",
      "district":"XYZ",
      "state":"Al-Riyadh",
      "country_code":"AE",
      "lat":10.01,
      "long":10.01
   },
   "additional":{
      "enable_whatsapp":false,
      "order_date":"2017-02-14",
      "ship_date":"2017-02-14",
      "min_edd":2,
      "max_edd":4,
      "language_code":"eng"
   }
}

Sample Response

{
    "meta": {
        "status": 200,
        "message": "Success",
        "success": true
    },
    "result": {
        "tracking_id": 491179766,
        "security_key": "067238b4-7e55-4d4d-92d1-1a72028e5b64"
    }
}

{
    "meta": {
        "status": 303,
        "message": "Waybill already registered",
        "success": false
    },
    "result": {
        "tracking_id": 267984163,
        "security_key": "37317af1-f3c3-4c41-b563-99b5c601e59d"
    }
}

{
    "meta": {
        "status": 353,
        "message": "Clickpost Account: Inactive",
        "success": false
    }
}