Introduction
Welcome to the Clickpost API! You can use our API to access Clickpost API endpoints which can get information on our different APIs:
- Recommendation Engine API: Recommend list of Courier Partners in priority order
- Manifestation API: Create order on Courier Partner and fetch AWB, Cancel orders and place pickup request
- Shipping Label Generation API: Generating new shipping label or get the one generated in Manifestation Request
- Track Shipment API: Track your shipment using AWB and Courier Partner.
- Cancellation API: Cancel shipment manifested on Courier Partner for faster returns and higher inventory availability
- Serviceability, Cost, TAT API: Check pincode serviceability, cost for shipping and turn around time for the delivery.
- Expected Date of Delivery API: Check predictive sla time range for any shipment
- Pickup Request API: Recommend list of Courier Partners in priority order
- Operation and Customer Feedback API: Gives list of customer feedbacks and operations feedback on the tracking page.
- NDR Action update API: Updates the after NDR action directly on courier company’s database.
- Return Webhooks: Track your return shipment using AWB and Courier Partner using webhooks (we give data on your endpoint).
You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Recommendation API
URL to hit
https://www.clickpost.in/api/v1/recommendation_api/?key=2e9b19ac-8e1f-41ac-a35b-4cd23f41ae17
(key needs to be replaced with the key provided to you)
Example(POST Body)
[{
"pickup_pincode": "110017",
"drop_pincode": "110019",
"order_type": "PREPAID",
"reference_number": "1",
"item": "bottle",
"invoice_value": 1245,
"delivery_type": "FORWARD",
"weight": 10,
"height": 10,
"length": 10,
"breadth": 10
}]
Response
{
"result": [
{
"form_tax_details": [
{
"entry_tax": false,
"form_name": ""
}
],
"request_details": {
"order_type": "PREPAID",
"drop_pincode": "110019",
"reference_number": "1",
"delivery_type": "FORWARD",
"pickup_pincode": "110017",
"invoice_value": 1245,
"item": "bottle"
},
"preference_array": [
{
"cp_name": "Fedex",
"cp_id": 1,
"account_code": "Fedex Economy",
"priority": 1
},
{
"cp_name": "Fedex",
"cp_id": 1,
"account_code": "Fedex Standard Overnight",
"priority": 2
}
],
"pincode_serviceable": true
}
],
"meta": {
"message": "SUCCESS",
"success": true,
"status": 200
}
}
It’s a POST request as follows
URL:
https://www.clickpost.in/api/v1/recommendation_api/
Headers: {‘Content-type’: 'application/json’}
URL Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | character | API key provided to you |
POST Parameters:
Format: JSON
Compulsory Fields
Payload is a list of json objects each of which have following fields:
| Parameter | Type | Description |
|---|---|---|
| pickup_pincode | integer | pincode of pickup address |
| drop_pincode | integer | pincode of drop address |
| order_type | character | COD/PREPAID |
| reference_number | character | to identify each json object uniquely |
| item | character | item that you wish to send |
| invoice_value | double | invoice value of the shipment |
| delivery_type | character | FORWARD/RVP |
Optional Fields
In case you want the recommendation logic to incorporate pricing as a parameter as well please pass the following fields in the API. If not passed, the pricing given by you in the system will not be entertained as a parameter.
| Parameter | Type | Description |
|---|---|---|
| weight | integer | weight of the shipment |
| length | integer | length of the shipment |
| breadth | integer | breadth of the shipment |
| height | integer | height of the shipment |
Response explanation:
Response object has two parts:
- meta: stores information about the API, success or failure
- success: true/false, tells whether the order was created or not
- message: SUCCESS in case order was created successfully, else returns error message.
- status:
- 200 if the order is created successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result: It’s a list of multiple objects, each corresponding to the request json objects, with unique identifier: reference_number. For each json object in result, refer:
- pincode_serviceable: this field will let you know whether the pincode is serviceable by any courier partner or not. Values: true: if the pincode is serviceable else false
- preference_array: it’s the list of eligible courier partners for the corresponding reference_number. It has following fields
- cp_id: courier partner id as mentioned on page 1 of this document
- cp_name: name of the courier partner
- account_code: account code created while adding credentials on Clickpost dashboard, this is useful if you have multiple accounts for a courier partner
- priority: priority
Shipment Manifestation / AWB Generation API
Order Creation V1 API
URL to hit:
https://www.clickpost.in/api/v1/create-order/?username=<user-name>&key=<api-key>
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Example: POST Body (COD Shipment)
{
"pickup_name": "Heronakamura",
"pickup_phone": "9999999999",
"pickup_address": "1, Top Floor, Canaught Place, New Delhi",
"pickup_city": "Delhi",
"pickup_state": "DL",
"pickup_country": "IN",
"pickup_pincode": "110001",
"pickup_time": "2017-02-14T18:00:00+05:30",
"drop_name": "Rahul Jagat",
"drop_phone": "8080808080",
"drop_address": "KFC, Kalkaji Main Road, New Delhi",
"drop_city": "DELHI",
"drop_state": "DELHI",
"drop_country": "IN",
"drop_pincode": "110020",
"return_info": {
"pincode": "110019",
"city": "DELHI",
"name": "Deepanshu",
"state": "DELHI",
"country": "IN",
"phone": 8080808080,
"address": "Test Address top floor kalkaji New Delhi "
},
"tin": "00000000",
"invoice_date": "2016-12-16",
"order_type": "PREPAID",
"cod_value": 0,
"items": [{"product_url":"<Product Page Url>", "price":"370.00","description":"IN1543MTOSKTBLA-146-10","sku":"IN1543MTOSKTBLA-146-10","quantity":"1","images": "http://sample-file1.jpg,http://sample-file2.jpg"},{"product_url":"<Product Page Url>","price":"694.00","description":"IN1516MTODREMLT-147-10","sku":"IN1516MTODREMLT-147-10","quantity":"1","images": "http://sample-file1.jpg,http://sample-file2.jpg"}],
"invoice_number": "123465",
"invoice_value": 1006.00,
"reference_number": "SAMPLE-REF-No",
"email": "founders@clickpost.in",
"weight": 500,
"length": 5,
"height": 10,
"breadth": 15,
"courier_partner": 2,
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"gst_tax_base": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100
}
}
Response
{
"meta": {
"message": "Order Placed Successfully",
"status": 200,
"success": true
},
"result": {
"reference_number": "SAMPLE-REF-No",
"waybill": "785578015860",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/fedex/2017-02-11/785578015860.pdf"
}
}
Example: POST Body (PREPAID Shipment)
{
"pickup_address": "B-220/2, 1st Floor, Right Door, Savitri
Nagar, New Delhi",
"pickup_city": "DELHI",
"pickup_state": "DELHI",
"pickup_country": "IN",
"pickup_pincode": "110017",
"pickup_time": "2015-12-10T12:00:00Z",
"drop_name": "Rahul",
"drop_phone": "8376035546",
"drop_address": "L-19B, Third Floor, Malviya Nagar, New
Delhi",
"drop_city": "delhi",
"pickup_name": "Deepanshu",
"pickup_phone": "8376035546",
"drop_state": "DL",
"drop_country": "IN",
"drop_pincode": "110092",
"return_info": {
"pincode": "110019",
"city": "DELHI",
"name": "Clickpost",
"state": "DELHI",
"country": "IN",
"phone": 8080808080,
"address": "Test Address, Test Location, Test Landmark New Delhi"
},
"tin": "120349483",
"invoice_date": "2015-12-27",
"order_type": "PREPAID",
"cod_value": "0",
"items": [{"product_url":"<Product Page Url>","price":"370.00","description":"IN1543MTOSKTBLA-146-10","sku":"IN1543MTOSKTBLA-146-10","quantity":"1","images": "http://sample-file1.jpg,http://sample-file2.jpg"},{"product_url":"<Product Page Url>","price":"694.00","description":"IN1516MTODREMLT-147-10","sku":"IN1516MTODREMLT-147-10","quantity":"1","images":"http://sample-file1.jpg,http://sample-file2.jpg"}],
"invoice_number": "INV-234/3",
"invoice_value": "100",
"reference_number": "SAMPLE-REF-No",
"email": "founders@clickpost.in",
"weight": "10",
"length": "10",
"height": "10",
"breadth": "10",
"courier_partner": 5,
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"gst_tax_base": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100
}
}
Example: POST Body: (Reverse Pickup: RVP Shipment):
{
"courier_partner": 7,
"email": "founders@clickpost.in",
"pickup_name": "Deepanshu",
"pickup_phone": "8080808080",
"pickup_address": "B-220/2, 1st Floor, Right Door, Savitri Nagar,
New Delhi",
"pickup_pincode": "110017",
"pickup_city": "DELHI",
"pickup_state": "DELHI",
"pickup_country": "IN",
"drop_name": "Rahul",
"drop_phone": "8080808080",
"drop_address": "L-19B, third Floor Malviya Nagar, New Delhi",
"drop_pincode": "110017",
"drop_city": "DELHI",
"drop_state": "DELHI",
"drop_country": "IN",
"order_type": "PREPAID",
"cod_value": 0,
"tin": "120349483",
"invoice_number": "INV-4/3",
"invoice_value": 100,
"invoice_date": "2015-12-27",
"items": [{"product_url":"<Product Page Url>", "price": 200, "description": "item1", "sku":
"XYZ1", "quantity": 1, "images": "http://sample-file1.jpg,http://sample-file2.jpg"}],
"height": 10,
"length": 10,
"breadth": 10,
"weight": 100,
"reference_number": "sok56sjkaphf",
"pickup_time": "2016-10-01T12:00:00Z",
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"gst_tax_base": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100
},
"rvp_reason": "Not Interested",
"delivery_type": "RVP"
}
Example: POST Body: (Reverse Pickup with QC detail RVP Shipment[Only for Shadowfax Reverse]):
{
"courier_partner": 7,
"email": "founders@clickpost.in",
"pickup_name": "Deepanshu",
"pickup_phone": "8080808080",
"pickup_address": "B-220/2, 1st Floor, Right Door, Savitri Nagar, New Delhi",
"pickup_pincode": "110017",
"pickup_city": "DELHI",
"pickup_state": "DELHI",
"pickup_country": "IN",
"drop_name": "Rahul",
"drop_phone": "8080808080",
"drop_address": "L-19B, third Floor Malviya Nagar, New Delhi",
"drop_pincode": "110017",
"drop_city": "DELHI",
"drop_state": "DELHI",
"drop_country": "IN",
"order_type": "PREPAID",
"cod_value": 0,
"tin": "120349483",
"invoice_number": "INV-4/3",
"invoice_value": 100,
"invoice_date": "2015-12-27",
"items": [
{"product_url":"<Product Page Url>",
"price": 200,
"description": "item1",
"sku": "XYZ1",
"quantity": 1,
"qc_type": "doorstep",
"cat": "electronics",
"sub_cat": "tv",
"image_urls":[
"https://assetscdn.paytm.com/images/catalog/view_item/114560/1494268990652.jpg",
"https://assetscdn.paytm.com/images/catalog/view_item/116303/1493891914950.jpg"
]
}
],
"height": 10,
"length": 10,
"breadth": 10,
"weight": 100,
"reference_number": "sok56sjkaphf",
"pickup_time": "2016-10-01T12:00:00Z",
"rvp_reason": "Not Interested",
"delivery_type": "RVP",
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100
}
}
The create order API allows uploading the package details (manifest information) into the courier partner’s system and returns a label generated by them. You can create single order; errors/warnings will be highlighted in the response.
Please note, in case of any validation failure - order will not get created. Please wait for 8 seconds before you reject a rest-request for latency.
The API is a HTTP POST request to: https://www.clickpost.in/api/v1/create-order/ where output format is json.
Listed below are the parameters:
URL parameters:
| Parameter | Type | Description |
|---|---|---|
| Username | character | User name provided to you |
| key | character | API key provided to you |
POST Parameters:
Format: JSON
Compulsory Fields:
Pickup information
| Parameter | Type | Description |
|---|---|---|
| pickup_name | character | maximum length of 100 characters |
| pickup_phone | integer | 10/11 digit phone number |
| pickup_pincode | integer | 6 digit pincode |
| pickup_address | character | maximum length of 500 characters |
| pickup_time | character | (ISO Format: example 2015-12-10T12:00:00Z) |
| pickup_city | character | pickup city name, maximum length 200 characters |
| pickup_state | character | pickup state name, maximum length 200 characters |
| pickup_country | character | pickup country name, maximum length 100 characters i. email: email id to be sent to courier partner for this shipment |
| vendor_code | character | (optional) vendor code of pickup location. If this field is not provided, Clickpost will generate vendor code for the pickup location |
Drop Information
| Parameter | Type | Description |
|---|---|---|
| drop_name | character | maximum length of 100 characters |
| drop_address | character | maximum length of 500 characters |
| drop_phone | integer | 10/11 digit phone number |
| drop_pincode | integer | 6 digit pincode |
| drop_city | character | drop city name, maximum length 200 characters |
| drop_state | character | drop state name, maximum length 200 characters |
| drop_country | character | drop country name, maximum length 200 characters |
| drop_email | character | (optional) email of the customer |
Return Information
| Parameter | Type | Description |
|---|---|---|
| name | character | maximum length of 100 characters |
| address | character | maximum length of 500 characters |
| phone | integer | 10/11 digit phone number |
| pincode | integer | 6 digit pincode |
| city | character | drop city name, maximum length 200 characters |
| state | character | drop state name, maximum length 200 characters |
| country | character | drop country name, maximum length 200 characters |
| character | (optional) email of the customer |
Shipment details
| Parameter | Type | Description |
|---|---|---|
| items | List | Json list with multiple item objects in it. Each item object should have following: |
| price | double | price of the item |
| description | character | Item description |
| sku | character | SKU unit name of item |
| quantity | Integer | number of item pieces |
| product_url | string | url of the product on the website |
| invoice_value | decimal/float/integer | value |
| invoice_number | character | string of length 50 characters |
| invoice_date | character | (Format: YYYY-MM-DD, example: 2015-12-25 for 25th December 2015) |
| reference_number | character | reference number to tag the order with your order id. Reference number has to follow Code 39 standards (https://en.wikipedia.org/wiki/Code_39) |
| length | integer | in cm |
| breadth | integer | in cm |
| height | integer | in cm |
| weight | integer | grams |
| tin | character | TIN number of seller (Now GST No) |
| images | character | comma separated images of the item |
GST Information
| Parameter | Type | Description |
|---|---|---|
| enterprise_gstin | string | GST No of enterprise shipping the shipment |
| seller_gstin | string | GST No of seller sending the shipment (will be different from above for marketplaces) |
| taxable_value | double | taxable amount for GST (generally invoice_value of shipment) |
| ewaybill_serial_number | string | ewaybill for the shipment (optional) |
| is_seller_registered_under_gst | boolean | True / False, depending on whether you are registered for GST |
| place_of_supply | string | place of supply of service/product (https://cleartax.in/s/gst-state-code-jurisdiction) |
| gst_discount | double | discount given under gst, if any (optional) |
| hsn_code | string | HSN code for the product shipped (You may search for HSN https://cleartax.in/s/gst-hsn-lookup) |
| gst_total_tax | double | total GST applicable for the shipment |
| sgst_tax_rate | integer | tax percent applicable for sgst for the shipment (optional) |
| sgst_amount | double | amount applicable for sgst for the shipment (optional) |
| igst_tax_rate | integer | tax percent applicable for igst for the shipment (optional) |
| igst_amount | double | amount applicable for igst for the shipment (optional) |
| cgst_tax_rate | integer | tax percent applicable for cgst for the shipment (optional) |
| cgst_amount | double | amount applicable for cgst for the shipment (optional) |
| consignee_gstin | string | GST No of consignee (compulsory for B2B shipments) |
| invoice_reference | string | invoice number for the shipment |
Order type:
| Parameter | Type | Description |
|---|---|---|
| order_type | character | COD/PREPAID |
| cod_value: if order_type = COD | double | cod_value should be greater than 0 |
| cod_value: if order_type = PREPAID | double | cod_value should be equal to 0 |
Courier Partner:
| Parameter | Type | Description |
|---|---|---|
| courier_partner | integer | ID of courier partner for which the order is to be placed. |
List of courier partners is present at: http://track.clickpost.in/courier_partner
Compulsory fields for RVP order creation:
| Parameter | Type | Description |
|---|---|---|
| rvp_reason | character | stating the reason for Reverse Pickup |
| delivery_type | character | For Reverse Pickup, the value of this field should be “RVP” |
Optional field for NuvoEx RVP (Doorstep QC):
| Parameter | Type | Description |
|---|---|---|
| qc_type | character | pass “doorstep” if you want reverse pickup to be done as doorstep quality check as leave it blank |
| image_urls | character | add this field in items array for each item. value will be comma seperated url strings without spaces. |
| cat | character | category of product for qc questions to be asked at doorstep. To be passed in items array for each item object |
| sub_cat | character | sub category of product for qc questions to be asked at doorstep. To be passed in items array for each item object |
Optional field for Bluedart (Critical / Time defined delivery service):
| Parameter | Type | Description |
|---|---|---|
| service_type | character | If you are using Critical shipment service, Time Defined delivery Service (10:30 am or 12 noon next day), Please pass this field with values: |
- C: Critical Shipment
- T: Time defined delivery on or before 10:30
- N: Time defined delivery on or before 12
Response Explanation:
Response Object has two parts:
- meta: stores information about the API, success or failure
- “success”: true/false, tells whether the order was created or not
- “message”: SUCCESS in case order was created successfully, else returns error
- “status”:
- 200 if the order is created successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result:
- reference_number: reference number provided in the post data
- waybill: waybill generated by courier partner for the shipment
- label: AWS link of the label generated for the shipment (Not generated for RVP shipments) Additional fields for Bluedart:
- DestinationLocation: 3 digit destination location code needed by Bluedart on shipping label
- DestinationArea: 3 digit destination area code needed by Bluedart on shipping label
Order Creation V3 API (Forward)
URL to hit:
https://www.clickpost.in/api/v3/create-order/?username=<user-name>&key=<api-key>
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Example: POST Body (COD Shipment)
{
"pickup_info": {
"pickup_state": "DELHI",
"pickup_address": "A-228 top floor kalkaji New Delhi ",
"email": "deepanshu.kartikey@pyck.in",
"pickup_time": "2017-05-20T12:00:00Z",
"pickup_pincode": "110019",
"pickup_city": "DELHI",
"tin": "120349483",
"pickup_name": "Deepanshu",
"pickup_country": "IN",
"pickup_phone": "9816691388"
},
"drop_info": {
"drop_address": "F-68 third floor kalkaji New Delhi ",
"drop_phone": "9717732407",
"drop_country": "IN",
"drop_state": "DELHI",
"drop_pincode": "110019",
"drop_city": "Delhi",
"drop_name": "Prashant"
},
"shipment_details": {
"height": 12,
"order_type": "COD",
"invoice_value": 200,
"invoice_number": "INV123",
"invoice_date": "2015-12-27",
"reference_number": "Order-1232",
"length": 10,
"breadth": 10,
"weight": 100,
"items": [
{
"product_url":"<Product Page Url>",
"price": 200,
"description": "item1",
"additional": {
"length": 10,
"height": 10,
"breadth": 10,
"weight": 100,
"images": "http://sample-file1.jpg,http://sample-file2.jpg"
},
"quantity": 1,
"sku": "XYZ1"
}
],
"cod_value": 200,
"courier_partner": 3
},
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"gst_tax_base": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100
},
"additional": {
"label": true,
"return_info": {
"pincode": "110019",
"address": "Test Address top floor kalkaji NewDelhi ",
"state": "DELHI",
"phone": "8080808080",
"name": "Deepanshu",
"city": "DELHI",
"country": "IN"
},
"awb_number": "43062728295",
"delivery_type": "FORWARD",
"async": false,
"gst_number" : "21313",
"account_code": "<account_code generated via clickpost dashboard>"
}
}
Response
{
"meta": {
"message": "Order Placed Successfully",
"status": 200,
"success": true
},
"result": {
"sort_code": null,
"reference_number": "ASDF1234",
"waybill": "785578015860",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/fedex/2017-02-11/785578015860.pdf"
}
}
Example: POST Body (PREPAID Shipment)
{
"pickup_info": {
"pickup_state": "DELHI",
"pickup_address": "A-228 top floor kalkaji New Delhi ",
"email": "support@clickpost.in",
"pickup_time": "2017-05-20T12:00:00Z",
"pickup_pincode": "110019",
"pickup_city": "DELHI",
"tin": "120349483",
"pickup_name": "Deepanshu",
"pickup_country": "IN",
"pickup_phone": "8080808080"
},
"drop_info": {
"drop_address": "F-68 third floor kalkaji New Delhi ",
"drop_phone": "8080808080",
"drop_country": "IN",
"drop_state": "DELHI",
"drop_pincode": "110019",
"drop_city": "Delhi",
"drop_name": "Prashant"
},
"shipment_details": {
"height": 12,
"order_type": "PREPAID",
"invoice_value": 200,
"invoice_number": "INV123",
"invoice_date": "2015-12-27",
"reference_number": "Order-1232",
"length": 10,
"breadth": 10,
"weight": 100,
"items": [
{
"product_url":"<Product Page Url>",
"price": 200,
"description": "item1",
"additional": {
"length": 10,
"height": 10,
"breadth": 10,
"weight": 100,
"images": "http://sample-file1.jpg,http://sample-file2.jpg"
},
"quantity": 1,
"sku": "XYZ1"
}
],
"cod_value": 0,
"courier_partner": 3
},
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"gst_tax_base": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100
},
"additional": {
"label ": true,
"return_info": {
"pincode": "110019",
"address": "Test Address top floor kalkaji New Delhi ",
"state": "DELHI",
"phone": "8080808080",
"name": "Deepanshu",
"city": "DELHI",
"country": "IN"
},
"awb_number": "43062728295",
"delivery_type": "FORWARD",
"async": false,
"gst_number" : "21313",
"account_code": "ecom surface"
}
}
The create order API allows uploading the package details (manifest information) into the courier partner’s system and returns a label generated by them. You can create single order; errors/warnings will be highlighted in the response.
Please note, in case of any validation failure - order will not get created. Please wait for 8 seconds before you reject a rest-request for latency.
Async flag in additional object allows users to choose if order need to be generated in real time or in background. For bulk order creation async=true is recommended. Orders data in case of async is provided via webhooks.
The API is a HTTP POST request to: https://www.clickpost.in/api/v3/create-order/ where output format is json.
Listed below are the parameters:
URL parameters:
| Parameter | Type | Description |
|---|---|---|
| username | character | User name provided to you |
| key | character | API key provided to you |
POST Parameters:
Format: JSON
Compulsory Fields:
Pickup information
| Parameter | Type | Description |
|---|---|---|
| pickup_name | character | maximum length of 100 characters |
| pickup_phone | character | 10/11 digit phone number |
| pickup_pincode | character | 6 digit pincode |
| pickup_address | character | maximum length of 500 characters |
| pickup_time | character | (ISO Format: example 2015-12-10T12:00:00Z) |
| pickup_city | character | pickup city name, maximum length 200 characters |
| pickup_state | character | pickup state name, maximum length 200 characters |
| pickup_country | character | pickup country name, maximum length 100 characters |
| character | email id to be sent to courier partner for this shipment | |
| tin | character | Seller TIN if available. If not, please pass GST No here |
Drop Information
| Parameter | Type | Description |
|---|---|---|
| drop_name | character | maximum length of 100 characters |
| drop_address | character | maximum length of 500 characters |
| drop_phone | character | 10/11 digit phone number |
| drop_pincode | character | 6 digit pincode |
| drop_city | character | drop city name, maximum length 200 characters |
| drop_state | character | drop state name, maximum length 200 characters |
| drop_country | character | drop country name, maximum length 200 characters |
| drop_email | character | (optional) email of the customer |
Return Information
| Parameter | Type | Description |
|---|---|---|
| name | character | maximum length of 100 characters |
| address | character | maximum length of 500 characters |
| phone | integer | 10/11 digit phone number |
| pincode | integer | 6 digit pincode |
| city | character | drop city name, maximum length 200 characters |
| state | character | drop state name, maximum length 200 characters |
| country | character | drop country name, maximum length 200 characters |
| character | (optional) email of the customer |
Shipment details
| Parameter | Type | Description |
|---|---|---|
| items | List | Json list with multiple item objects in it. Each item object should have following: |
| price | double | price of the item |
| description | character | Item description |
| sku | character | SKU unit name of item |
| quantity | Integer | number of item pieces (should be always > 0) |
| product_url | character | product page url for the item on website |
| invoice_value | decimal/float/integer | value |
| invoice_number | character | string of length 50 characters |
| invoice_date | character | Format: YYYY-MM-DD, example: 2015-12-25 for 25th December 2015 |
| reference_number | character | reference number to tag the order with your order id. |
| length | integer | length of shipment in cm |
| breadth | integer | breadth of shipment in cm |
| height | integer | height of shipment in cm |
| weight | integer | weight of shipment in grams |
| tin | character | TIN number of seller (Now GST No) |
| images | character | comma separated images of the item |
Order type:
| Parameter | Type | Description |
|---|---|---|
| order_type | character | COD/PREPAID/EXCHANGE, to be passed in shipment_details object |
| cod_value | double | if order_type = COD, cod_value should be greater than 0, if order_type = PREPAID, cod_value should be equal to 0. To be passed in shipment_details object |
Courier Partner:
| Parameter | Type | Description |
|---|---|---|
| courier_partner | integer | ID of courier partner for which the order is to be placed. This is to be passed in shipment_details object |
| account_code | character | (optional) in case you have multiple accounts for a courier partner in Clickpost, code of account saved in clickpost is to be passed in additional object |
List of courier partners is present at: http://track.clickpost.in/courier_partner
GST Information
| Parameter | Type | Description |
|---|---|---|
| enterprise_gstin | string | GST No of enterprise shipping the shipment |
| seller_gstin | string | GST No of seller sending the shipment (will be different from above for marketplaces) |
| taxable_value | double | taxable amount for GST (generally invoice_value of shipment) |
| ewaybill_serial_number | string | ewaybill for the shipment (optional) |
| is_seller_registered_under_gst | boolean | True / False, depending on whether you are registered for GST |
| place_of_supply | string | place of supply of service/product (https://cleartax.in/s/gst-state-code-jurisdiction) |
| gst_discount | double | discount given under gst, if any (optional) |
| hsn_code | string | HSN code for the product shipped (You may search for HSN https://cleartax.in/s/gst-hsn-lookup) |
| gst_total_tax | double | total GST applicable for the shipment |
| sgst_tax_rate | integer | tax percent applicable for sgst for the shipment (optional) |
| sgst_amount | double | amount applicable for sgst for the shipment (optional) |
| igst_tax_rate | integer | tax percent applicable for igst for the shipment (optional) |
| igst_amount | double | amount applicable for igst for the shipment (optional) |
| cgst_tax_rate | integer | tax percent applicable for cgst for the shipment (optional) |
| cgst_amount | double | amount applicable for cgst for the shipment (optional) |
| consignee_gstin | string | GST No of consignee (compulsory for B2B shipments) |
| invoice_reference | string | invoice number for the shipment |
additional object
| Parameter | Type | Description |
|---|---|---|
| label | boolean | true or false based upon if label need to be generated |
| return_info | object | return info object information if needed |
| awb_number | character | awb number if available |
| delivery_type | character | FORWARD or RVP |
| rvp_reason | character | rvp reason if order is for reverse pickup |
| priority | character | “NORMAL” or any other priority for order |
| async | boolean | for real time orders false and true if order need to generated in background |
| gst_number | character | gst number for tax purposes |
| pickup_type | character | Acceptable values: “WH” (for warehouse pickup) / “SL” (for seller pickup [marketplace]). This value is passed to EcomExpress only |
| vendor_code | character | (optional) vendor code of pickup location. If this field is not provided, Clickpost will generate vendor code for the pickup location. For Ecom Express this field is passed to them as pickup_location_code to create location tagging |
Optional field for Bluedart (Critical / Time defined delivery service):
| Parameter | Type | Description |
|---|---|---|
| service_type | character | If you are using Critical shipment service, Time Defined delivery Service (10:30 am or 12 noon next day), Please pass this field with values: |
- C: Critical Shipment
- T: Time defined delivery on or before 10:30
- N: Time defined delivery on or before 12
Response Explanation:
Response Object has two parts:
- meta: stores information about the API, success or failure
- “success”: true/false, tells whether the order was created or not
- “message”: SUCCESS in case order was created successfully, else returns error
- “status”:
- 200 if the order is created successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result:
- reference_number: reference number provided in the post data
- waybill: waybill generated by courier partner for the shipment
- label: AWS link of the label generated for the shipment (Not generated for RVP shipments)
- sort_code: Sort Code of shipment, needed by certain logistics partner on the label. response will be null if the sort code is not applicable for logistics partner. Right now populated for Delhivery / Ecom / Bluedart / XpressBees.
Additional fields for Bluedart: 5. DestinationLocation: 3 digit destination location code needed by Bluedart on shipping label 6. DestinationArea: 3 digit destination area code needed by Bluedart on shipping label
Order Creation V3 API (Reverse)
https://www.clickpost.in/api/v3/create-order/?username=<user-name>&key=<api-key>
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Example: POST Body
{
"pickup_info": {
"pickup_state": "DELHI",
"pickup_address": "A-228 top floor kalkaji New Delhi ",
"email": "support@clickpost.in",
"pickup_time": "2017-05-20T12:00:00Z",
"pickup_pincode": "110019",
"pickup_city": "DELHI",
"tin": "120349483",
"pickup_name": "Deepanshu",
"pickup_country": "IN",
"pickup_phone": "8080808080"
},
"drop_info": {
"drop_address": "F-68 third floor kalkaji New Delhi ",
"drop_phone": "8080808080",
"drop_country": "IN",
"drop_state": "DELHI",
"drop_pincode": "110019",
"drop_city": "Delhi",
"drop_name": "Prashant"
},
"shipment_details": {
"height": 12,
"order_type": "PREPAID",
"invoice_value": 200,
"invoice_number": "INV123",
"invoice_date": "2015-12-27",
"reference_number": "Order-1232",
"length": 10,
"breadth": 10,
"weight": 100,
"items": [
{
"product_url":"<Product Page Url>",
"price": 200,
"description": "item1",
"additional": {
"length": 10,
"height": 10,
"breadth": 10,
"weight": 100
},
"quantity": 1,
"sku": "XYZ1",
"image_urls": [
"https://assetscdn.paytm.com/images/catalog/view_item/114560/123.jpg",
"https://assetscdn.paytm.com/images/catalog/view_item/116303/123434.jpg"
]
}
],
"cod_value": 0,
"courier_partner": 24
},
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"gst_tax_base": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100
},
"additional": {
"label ": true,
"awb_number": "43062728295",
"delivery_type": "RVP",
"rvp_reason": "Shipper cancellation",
"async": false,
"account_code": "ecom reverse"
}
}
- All parameter definition remains same as manifestation v3 Forward API
- Following parameters are the changes in manifestation v3 Forward API:
Compulsory fields for RVP order creation:
| Parameter | Type | Description |
|---|---|---|
| rvp_reason | character | stating the reason for Reverse Pickup |
| delivery_type | character | For Reverse Pickup, the value of this field should be “RVP” |
Optional field for RVP (Doorstep QC):
| Parameter | Type | Description |
|---|---|---|
| qc_type | character | pass “doorstep” if you want reverse pickup to be done as doorstep quality check as leave it blank |
| image_urls | character | add this field in items array for each item. value will be comma seperated url strings without spaces. |
| cat | character | category of product for qc questions to be asked at doorstep. To be passed in items array for each item object |
| sub_cat | character | sub category of product for qc questions to be asked at doorstep. To be passed in items array for each item object |
Multiseller items shipment API
https://www.clickpost.in/api/v3/create-order/?username=<user-name>&key=<api-key>
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Example: POST Body
{
"pickup_info": {
"pickup_time": "2017-09-20T12:00:00Z",
"email": "pankaj@khazanabazaar.com",
"pickup_address": "402, Orbit tower, Sahara Darwaja, Ring Road, Surat - 395002",
"pickup_state": "GUJARAT",
"pickup_name": "Pankaj Kubadiya",
"pickup_country": "IN",
"tin": "120349483",
"pickup_city": "SURAT",
"pickup_phone": "08469591430",
"pickup_pincode": "395002"
},
"drop_info": {
"drop_country": "IN",
"drop_city": "Delhi",
"drop_phone": "9717732402",
"drop_address": "F-68 third floor kalkaji New Delhi ",
"drop_name": "Prashant",
"drop_state": "DELHI",
"drop_pincode": "110019",
"drop_email": "support@clickpost.in"
},
"shipment_details": {
"breadth": 10,
"cod_value": 200,
"height": 12,
"invoice_date": "2015-12-27",
"length": 10,
"order_type": "COD",
"invoice_number": "INV123",
"invoice_value": 200,
"items": [{
"quantity": 1,
"sku": "XYZ1",
"price": 200,
"description": "item1",
"gst_info": {
"consignee_gstin": "1233",
"invoice_reference": "1234",
"seller_gstin": "1234",
"cgst_tax_rate": 100,
"place_of_supply": "DELHI",
"sgst_tax_rate": 100,
"igst_tax_rate": 100,
"enterprise_gstin": "13",
"gst_tax_base": 200,
"igst_amount": 100,
"is_seller_registered_under_gst": false,
"sgst_amount": 100,
"taxable_value": 100,
"gst_discount": 0,
"gst_total_tax": 100,
"hsn_code": "1234",
"ewaybill_serial_number": "2345677",
"cgst_amount": 200,
"invoice_value": 200,
"seller_name": "Deepanshu",
"seller_address": "A-228 top floor kalkaji",
"seller_state": "Delhi",
"seller_pincode": "110019",
"invoice_number": "1882782",
"invoice_date": "2018-08-23"
},
"additional": {
"breadth": 10,
"product_url":"<Product Page Url>",
"images": "http://sample-file1.jpg,http://sample-file2.jpg",
"length": 10,
"weight": 100,
"height": 10
}
}],
"courier_partner": 3,
"weight": 100,
"reference_number": "UNIQUE-SHIPMENT-ID"
},
"additional": {
"label": true,
"data_validation": true,
"async": false,
"return_info": {
"email": "support@clickpost.in",
"name": "Deepanshu",
"phone": "8080808080",
"address": "Test Address top floor Kalkaji New Delhi ",
"country": "IN",
"city": "DELHI",
"pincode": "110019",
"state": "DELHI"
},
"delivery_type": "FORWARD",
"vendor_code": "<WH_CODE>",
"pickup_type": "WH",
"is_multi_seller": true
}
}
Response
{
"meta": {
"message": "Order Placed Successfully",
"status": 200,
"success": true
},
"result": {
"sort_code": "DEL/SET",
"reference_number": "UNIQUE-SHIPMENT-ID",
"waybill": "785578015860",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/ECOM/2017-02-18/785578015860.pdf"
}
}
The create order Multi Seller shipment API allows uploading the package details (manifest information) into the courier partner’s system for single shipment having multiple items in it (having different GST values) and returns a label generated by them. You can create single order; errors/warnings will be highlighted in the response.
Please note, in case of any validation failure - order will not get created. Please wait for 8 seconds before you reject a rest-request for latency.
The API is a HTTP POST request to: https://www.clickpost.in/api/v3/create-order/ where output format is json.
All the parameters are same as manifestation v3 API. Changes are:
- gst_info added in shipment_details object
- is_multi_seller: true flag to be passed in the additional object.
Order Creation Multi Model API
URL to hit:
https://www.clickpost.in/api/v3/create-order/?username=<user-name>&key=<api-key>
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Example: POST Body
{
"pickup_info": {
"email": "mrigendrasinha@gmail.com",
"pickup_name": "Test Pickup Name",
"pickup_phone": "8080808080",
"pickup_address": "No.5, Pycroft Garden Road, Mohammed Sathak Trust, 5th Floor, Nungambakkam",
"pickup_pincode": "110016",
"pickup_city": "DELHI",
"pickup_state": "TAMILNADU",
"pickup_country": "IN",
"pickup_time": "2017-11-15T09:25:00.000Z",
"tin": "33030721658"
},
"drop_info": {
"drop_name": "Test Drop Name",
"drop_phone": "8080808080",
"drop_address": "No.5, Pycroft Garden Road, Mohammed Sathak Trust, 5th Floor, Nungambakkam",
"drop_pincode": "223045",
"drop_city": "BANGLORE",
"drop_state": "TAMILNADU",
"drop_country": "IN"
},
"shipment_details": {
"courier_partner": 5,
"height": 1,
"length": 1,
"breadth": 1,
"weight": 10,
"reference_number": "RE1234",
"order_type": "PREPAID",
"cod_value": 0,
"items": [{
"product_url":"<Product Page Url>",
"price": 1000,
"description": "dfdsfsd",
"sku": "asasa",
"quantity": 1,
"weight": 1
}],
"invoice_number": "INV123",
"invoice_value": 1000,
"invoice_date": "2017-11-11"
},
"gst_info": {
"seller_gstin": "1234",
"taxable_value": 100,
"ewaybill_serial_number": "2345677",
"is_seller_registered_under_gst": false,
"sgst_tax_rate": 100,
"place_of_supply": "DELHI",
"gst_discount": 0,
"hsn_code": "1234",
"sgst_amount": 100,
"enterprise_gstin": "13",
"gst_total_tax": 100,
"igst_amount": 100,
"cgst_amount": 200,
"gst_tax_base": 200,
"consignee_gstin": "1233",
"igst_tax_rate": 100,
"invoice_reference": "1234",
"cgst_tax_rate": 100
},
"additional": {
"data_validation": true,
"label": true,
"multi_modal": {
"last_mile_courier_partner": 5,
"last_mile_pickup_time": "2017-11-15 2:56 PM",
"last_mile_order_type": "PREPAID",
"transit_info": {
"transit_city": "CHANDIGARH",
"transit_state": "CHANDIGARH",
"transit_phone": "8080808080",
"transit_name": "Mr.Arun",
"transit_pincode": "160017",
"transit_address": "229A, 2nd Floor, Elante Mall, Industrial Area,Phase-1",
"transit_country": "IN",
"transit_email": "a@a.com"
}
}
}
}
Response
{
"order_id": 76703,
"meta": {
"status": 200,
"success": true,
"message": "Order Placed Successfully"
},
"result": {
"reference_number": "RE1234",
"DestinationArea": "CAR",
"waybill": "69573426016",
"label1": "https://pyck-res-bucket.s3.amazonaws.com:443/bluedart/2017-11-30/69573426016.pdf",
"waybill1": "69573426016",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/bluedart/2017-11-30/69573426016.pdf",
"DestinationLocation": "CMM"
},
"tracking_id": 3475042
}
The create order Multi Model API allows uploading the package details (manifest information) into the courier partner’s system for multi hop shipment (2 courier company do the delivery of shipment) and returns a label generated by them. You can create single order; errors/warnings will be highlighted in the response.
Please note, in case of any validation failure - order will not get created. Please wait for 8 seconds before you reject a rest-request for latency.
The API is a HTTP POST request to: https://www.clickpost.in/api/v3/create-order/ where output format is json.
Listed below are the parameters:
URL parameters:
| Parameter | Type | Description |
|---|---|---|
| Username | character | User name provided to you |
| key | character | API key provided to you |
POST Parameters:
Format: JSON
Compulsory Fields:
Pickup information
| Parameter | Type | Description |
|---|---|---|
| pickup_name | character | maximum length of 100 characters |
| pickup_phone | integer | 10/11 digit phone number |
| pickup_pincode | integer | 6 digit pincode |
| pickup_address | character | maximum length of 500 characters |
| pickup_time | character | (ISO Format: example 2015-12-10T12:00:00Z) |
| pickup_city | character | pickup city name, maximum length 200 characters |
| pickup_state | character | pickup state name, maximum length 200 characters |
| pickup_country | character | pickup country name, maximum length 100 characters i. email: email id to be sent to courier partner for this shipment |
| vendor_code | character | (optional) vendor code of pickup location. If this field is not provided, Clickpost will generate vendor code for the pickup location |
Drop Information
| Parameter | Type | Description |
|---|---|---|
| drop_name | character | maximum length of 100 characters |
| drop_address | character | maximum length of 500 characters |
| drop_phone | integer | 10/11 digit phone number |
| drop_pincode | integer | 6 digit pincode |
| drop_city | character | drop city name, maximum length 200 characters |
| drop_state | character | drop state name, maximum length 200 characters |
| drop_country | character | drop country name, maximum length 200 characters |
| drop_email | character | (optional) email of the customer |
Return Information
| Parameter | Type | Description |
|---|---|---|
| name | character | maximum length of 100 characters |
| address | character | maximum length of 500 characters |
| phone | integer | 10/11 digit phone number |
| pincode | integer | 6 digit pincode |
| city | character | drop city name, maximum length 200 characters |
| state | character | drop state name, maximum length 200 characters |
| country | character | drop country name, maximum length 200 characters |
| character | (optional) email of the customer |
Shipment details
| Parameter | Type | Description |
|---|---|---|
| items | List | Json list with multiple item objects in it. Each item object should have following: |
| price | double | price of the item |
| description | character | Item description |
| sku | character | SKU unit name of item |
| quantity | Integer | number of item pieces |
| product_url | character | item url on website |
| invoice_value | decimal/float/integer | value |
| invoice_number | character | string of length 50 characters |
| invoice_date | character | (Format: YYYY-MM-DD, example: 2015-12-25 for 25th December 2015) |
| reference_number | character | reference number to tag the order with your order id. |
| length | integer | in cm |
| breadth | integer | in cm |
| height | integer | in cm |
| weight | integer | grams |
| tin | character | TIN number of seller (Now GST No) |
GST Information
| Parameter | Type | Description |
|---|---|---|
| enterprise_gstin | string | GST No of enterprise shipping the shipment |
| seller_gstin | string | GST No of seller sending the shipment (will be different from above for marketplaces) |
| taxable_value | double | taxable amount for GST (generally invoice_value of shipment) |
| ewaybill_serial_number | string | ewaybill for the shipment (optional) |
| is_seller_registered_under_gst | boolean | True / False, depending on whether you are registered for GST |
| place_of_supply | string | place of supply of service/product (https://cleartax.in/s/gst-state-code-jurisdiction) |
| gst_discount | double | discount given under gst, if any (optional) |
| hsn_code | string | HSN code for the product shipped (You may search for HSN https://cleartax.in/s/gst-hsn-lookup) |
| gst_total_tax | double | total GST applicable for the shipment |
| sgst_tax_rate | integer | tax percent applicable for sgst for the shipment (optional) |
| sgst_amount | double | amount applicable for sgst for the shipment (optional) |
| igst_tax_rate | integer | tax percent applicable for igst for the shipment (optional) |
| igst_amount | double | amount applicable for igst for the shipment (optional) |
| cgst_tax_rate | integer | tax percent applicable for cgst for the shipment (optional) |
| cgst_amount | double | amount applicable for cgst for the shipment (optional) |
| consignee_gstin | string | GST No of consignee (compulsory for B2B shipments) |
| invoice_reference | string | invoice number for the shipment |
Order type:
| Parameter | Type | Description |
|---|---|---|
| order_type | character | COD/PREPAID |
| cod_value: if order_type = COD | double | cod_value should be greater than 0 |
| cod_value: if order_type = PREPAID | double | cod_value should be equal to 0 |
Courier Partner:
| Parameter | Type | Description |
|---|---|---|
| courier_partner | integer | ID of courier partner for which the order is to be placed. |
List of courier partners is present at: http://track.clickpost.in/courier_partner
Compulsory fields in additional object:
| Parameter | Type | Description |
|---|---|---|
| label | boolean | true or false based upon if label need to be generated |
| rvp_reason | character | rvp reason if order is for reverse pickup |
| priority | character | “NORMAL” or any other priority for order |
| return_info | object | return info object information if needed |
| awb_number | character | awb number if available |
| delivery_type | character | FORWARD or any other order type |
| async | boolean | for real time orders false and true if order need to generated in background |
| gst_number | character | gst number for tax purposes |
Transit address detail need to be passed in additional object:
| Parameter | Type | Description |
|---|---|---|
| last_mile_courier_partner | int | courier company id provided by us |
| last_mile_pickup_time | timestamp | pick up time for in transit hop (for last mile courier company) |
| last_mile_order_type | character | order type cod or prepaid for last mile |
| transit_city | character | transit city from where last mile pick the order for delivery |
| transit_state | character | transit state from where last mile pick the order for delivery |
| transit_phone | int | transit phone no |
| transit_name | character | person name from whol last mile picks the order |
| transit_pincode | int | pin code of location for last mile to pick |
| transit_address | character | address for last mile courier company to pick the order |
| transit_country | character | country code for the address |
| transit_email | character | email id for reference to pick order for last mile |
Optional field for Bluedart (Critical / Time defined delivery service):
| Parameter | Type | Description |
|---|---|---|
| service_type | character | If you are using Critical shipment service, Time Defined delivery Service (10:30 am or 12 noon next day), Please pass this field with values: |
- C: Critical Shipment
- T: Time defined delivery on or before 10:30
- N: Time defined delivery on or before 12
Response Explanation:
Response Object has two parts:
- meta: stores information about the API, success or failure
- “success”: true/false, tells whether the order was created or not
- “message”: SUCCESS in case order was created successfully, else returns error
- “status”:
- 200 if the order is created successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result:
- reference_number: reference number provided in the post data
- waybill: waybill generated by courier partner for the shipment
- label: AWS link of the label generated for the shipment (Not generated for RVP shipments) Additional fields for Bluedart:
- DestinationLocation: 3 digit destination location code needed by Bluedart on shipping label
- DestinationArea: 3 digit destination area code needed by Bluedart on shipping label
- waybill1: another waybill generated by courier partner for the shipment
- label1: Another AWS link of the label generated for the shipment (Not generated for RVP shipments)
Order Creation B2B API
URL to hit:
https://www.clickpost.in/api/v1/create-order/?username=<user-name>&key=<api-key>
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Example: POST Body
{
"pickup_info": {
"pickup_time": "2018-11-20T12:00:00Z",
"email": "support@clickpost.in",
"pickup_address": "Test Pickup Warehouse Address, Pickup Locality, Surat - 395002",
"pickup_state": "GUJARAT",
"pickup_name": "Test Pickup Warehouse Name",
"pickup_country": "IN",
"tin": "<GST_NUMBER>",
"pickup_city": "SURAT",
"pickup_phone": "8080808080",
"pickup_pincode": "395002"
},
"drop_info": {
"drop_country": "IN",
"drop_city": "Delhi",
"drop_phone": "8080808080",
"drop_address": "Test Drop address, Drop Locality, New Delhi ",
"drop_name": "Test Drop Name",
"drop_state": "DELHI",
"drop_pincode": "110020",
"drop_email": "support@clickpost.in"
},
"shipment_details": {
"breadth": 10,
"cod_value": 300,
"height": 12,
"invoice_date": "2018-11-12",
"length": 10,
"order_type": "COD",
"invoice_number": "INV123",
"invoice_value": 200,
"shipment_type": "MPS",
# Each item in items object represent a carton box.
"items": [{
"quantity": 1,
"sku": "XYZ1",
"price": 200,
"description": "Cartoon Box 1",
"gst_info": {
"consignee_gstin": "11ANKPT8882D1ZD",
"invoice_reference": "DC68HJJ",
"seller_gstin": "11ANKPT8882D1ZC",
"cgst_tax_rate": 100,
"place_of_supply": "DELHI",
"sgst_tax_rate": 100,
"igst_tax_rate": 100,
"enterprise_gstin": "13",
"gst_tax_base": 200,
"igst_amount": 100,
"is_seller_registered_under_gst": false,
"sgst_amount": 100,
"taxable_value": 100,
"gst_discount": 0,
"gst_total_tax": 100,
"hsn_code": "1234",
"cgst_amount": 200,
"invoice_value": 200,
"seller_name": "Deepanshu",
"seller_address": "A-228 top floor kalkaji",
"seller_state": "Delhi",
"seller_pincode": "110019",
"invoice_number": "1882782",
"invoice_date": "2018-08-23",
"ewaybill_serial_number": "07AACCF1234T3AS",
"ewaybill_expiry_date": "2018-12-31 18:58:56"
},
"additional": {
"breadth": 10,
"product_url":"<Product Page Url>",
"images": "http://sample-file1.jpg,http://sample-file2.jpg",
"length": 10,
"weight": 100,
"height": 10
}
},{
"quantity": 1,
"sku": "XYZ2",
"price": 200,
"description": "Cartoon Box 2",
"gst_info": {
"consignee_gstin": "11ANKPT8882D1ZD",
"invoice_reference": "DC68HJJ1",
"seller_gstin": "11ANKPT8882D1ZC",
"cgst_tax_rate": 100,
"place_of_supply": "DELHI",
"sgst_tax_rate": 100,
"igst_tax_rate": 100,
"enterprise_gstin": "13",
"gst_tax_base": 200,
"igst_amount": 100,
"is_seller_registered_under_gst": false,
"sgst_amount": 100,
"taxable_value": 100,
"gst_discount": 0,
"gst_total_tax": 100,
"hsn_code": "1234",
"cgst_amount": 200,
"invoice_value": 200,
"seller_name": "Deepanshu",
"seller_address": "A-228 top floor kalkaji",
"seller_state": "Delhi",
"seller_pincode": "110019",
"invoice_number": "1882783",
"invoice_date": "2018-08-23"
},
"additional": {
"breadth": 10,
"product_url":"<Product Page Url>",
"images": "http://sample-file1.jpg,http://sample-file2.jpg",
"length": 10,
"weight": 100,
"height": 10
}
}],
"courier_partner": 61,
"weight": 200,
"reference_number": "UNIQUE-SHIPMENT-ID7"
},
"additional": {
"label": true,
"data_validation": true,
"async": false,
"return_info": {
"email": "support@clickpost.in",
"name": "Test Return Warehouse Name",
"phone": "8080808080",
"address": "Test Return Address New Delhi ",
"country": "IN",
"city": "DELHI",
"pincode": "110020",
"state": "DELHI"
},
"delivery_type": "FORWARD",
"vendor_code": "SBL",
"pickup_type": "WH",
"is_multi_seller": true,
"account_code":"AIR"
}
}
Response
{
"meta": {
"message": "Order Placed Successfully",
"status": 200,
"success": true
},
"result": {
"reference_number": "ASDF1234",
"waybill": "785578015860",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/XPRESBEES_CARGO/2017-02-11/785578015860.pdf",
"children": [{
"reference_number": "ASDF1234",
"waybill": "785578015860_1",
"label": null,
"item": {
"height": 10,
"quantity": 1,
"price": 200,
"breadth": 10,
"description": "item1",
"weight": 100,
"waybill": "58402429105_1",
"sku": "XYZ1",
"length": 10
}
},
{
"reference_number": "ASDF1234",
"waybill": "785578015860_2",
"label": null,
"item": {
"height": 10,
"quantity": 1,
"price": 200,
"breadth": 10,
"description": "item2",
"weight": 100,
"waybill": "58402429105_1",
"sku": "XYZ2",
"length": 10
}
}
]
}
}
The create order B2B API allows uploading the package details (manifest information) for multi piece shipment into the courier partner’s system and returns a label generated by them. You can create single order; errors/warnings will be highlighted in the response.
Details for multiple shipments needs to passed in items array during object creation. This array is treated as multiple shipments/carton boxes if shipment_type is MPS.
Please note, in case of any validation failure - order will not get created. Please wait for 8 seconds before you reject a rest-request for latency.
The API is a HTTP POST request to: https://www.clickpost.in/api/v1/create-order/ where output format is json.
Listed below are the parameters:
URL parameters:
| Parameter | Type | Description |
|---|---|---|
| Username | character | User name provided to you |
| key | character | API key provided to you |
POST Parameters:
Format: JSON
Compulsory Fields:
Pickup information
| Parameter | Type | Description |
|---|---|---|
| pickup_name | character | maximum length of 100 characters |
| pickup_phone | integer | 10/11 digit phone number |
| pickup_pincode | integer | 6 digit pincode |
| pickup_address | character | maximum length of 500 characters |
| pickup_time | character | (ISO Format: example 2015-12-10T12:00:00Z) |
| pickup_city | character | pickup city name, maximum length 200 characters |
| pickup_state | character | pickup state name, maximum length 200 characters |
| pickup_country | character | pickup country name, maximum length 100 characters i. email: email id to be sent to courier partner for this shipment |
| vendor_code | character | (optional) vendor code of pickup location. If this field is not provided, Clickpost will generate vendor code for the pickup location |
Drop Information
| Parameter | Type | Description |
|---|---|---|
| drop_name | character | maximum length of 100 characters |
| drop_address | character | maximum length of 500 characters |
| drop_phone | integer | 10/11 digit phone number |
| drop_pincode | integer | 6 digit pincode |
| drop_city | character | drop city name, maximum length 200 characters |
| drop_state | character | drop state name, maximum length 200 characters |
| drop_country | character | drop country name, maximum length 200 characters |
| drop_email | character | (optional) email of the customer |
Return Information
| Parameter | Type | Description |
|---|---|---|
| name | character | maximum length of 100 characters |
| address | character | maximum length of 500 characters |
| phone | integer | 10/11 digit phone number |
| pincode | integer | 6 digit pincode |
| city | character | drop city name, maximum length 200 characters |
| state | character | drop state name, maximum length 200 characters |
| country | character | drop country name, maximum length 200 characters |
| character | (optional) email of the customer |
Shipment details
| Parameter | Type | Description |
|---|---|---|
| items | List | Json list with multiple item objects in it. Each item object represents a carton and should have following: |
| price | double | price of the item |
| description | character | Item description |
| sku | character | SKU unit name of item |
| length | integer | in cm |
| breadth | integer | in cm |
| height | integer | in cm |
| weight | integer | grams |
| quantity | Integer | number of sku pieces |
| product_url | character | product page url on website, optional |
| invoice_value | decimal/float/integer | value |
| invoice_number | character | string of length 50 characters |
| invoice_date | character | (Format: YYYY-MM-DD, example: 2015-12-25 for 25th December 2015) |
| reference_number | character | reference number to tag the order with your order id. |
| length | integer | in cm |
| breadth | integer | in cm |
| height | integer | in cm |
| weight | integer | grams |
| tin | character | TIN number of seller |
| shipment_type | character | MPS (Compulsory) |
GST Information
| Parameter | Type | Description |
|---|---|---|
| enterprise_gstin | string | GST No of enterprise shipping the shipment |
| seller_gstin | string | GST No of seller sending the shipment (will be different from above for marketplaces) |
| taxable_value | double | taxable amount for GST (generally invoice_value of shipment) |
| ewaybill_serial_number | string | ewaybill for the shipment (optional) |
| is_seller_registered_under_gst | boolean | True / False, depending on whether you are registered for GST |
| place_of_supply | string | place of supply of service/product (https://cleartax.in/s/gst-state-code-jurisdiction) |
| gst_discount | double | discount given under gst, if any (optional) |
| hsn_code | string | HSN code for the product shipped (You may search for HSN https://cleartax.in/s/gst-hsn-lookup) |
| gst_total_tax | double | total GST applicable for the shipment |
| sgst_tax_rate | integer | tax percent applicable for sgst for the shipment (optional) |
| sgst_amount | double | amount applicable for sgst for the shipment (optional) |
| igst_tax_rate | integer | tax percent applicable for igst for the shipment (optional) |
| igst_amount | double | amount applicable for igst for the shipment (optional) |
| cgst_tax_rate | integer | tax percent applicable for cgst for the shipment (optional) |
| cgst_amount | double | amount applicable for cgst for the shipment (optional) |
| consignee_gstin | string | GST No of consignee (compulsory for B2B shipments) |
| invoice_reference | string | invoice number for the shipment |
Order type:
| Parameter | Type | Description |
|---|---|---|
| order_type | character | COD/PREPAID |
| cod_value: if order_type = COD | double | cod_value should be greater than 0 |
| cod_value: if order_type = PREPAID | double | cod_value should be equal to 0 |
Courier Partner:
| Parameter | Type | Description |
|---|---|---|
| courier_partner | integer | ID of courier partner for which the order is to be placed. |
List of courier partners is present at: http://track.clickpost.in/courier_partner
Compulsory fields for RVP order creation:
| Parameter | Type | Description |
|---|---|---|
| rvp_reason | character | stating the reason for Reverse Pickup |
| delivery_type | character | For Reverse Pickup, the value of this field should be “RVP” |
Optional field for Bluedart (Critical / Time defined delivery service):
| Parameter | Type | Description |
|---|---|---|
| service_type | character | If you are using Critical shipment service, Time Defined delivery Service (10:30 am or 12 noon next day), Please pass this field with values: |
- C: Critical Shipment
- T: Time defined delivery on or before 10:30
- N: Time defined delivery on or before 12
Response Explanation:
Response Object has two parts:
- meta: stores information about the API, success or failure
- “success”: true/false, tells whether the order was created or not
- “message”: SUCCESS in case order was created successfully, else returns error
- “status”:
- 200 if the order is created successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result:
- reference_number: reference number provided in the post data
- waybill: waybill generated by courier partner for the shipment
- label: AWS link of the label generated for the shipment (Not generated for RVP shipments)
- All above details will be given for children awbs as well under children field along with item info, which is an array having label, awb and reference number for all the children Additional fields for Bluedart:
- DestinationLocation: 3 digit destination location code needed by Bluedart on shipping label
- DestinationArea: 3 digit destination area code needed by Bluedart on shipping label
Track Order
Register for Tracking Service
POST request. URL:
https://www.clickpost.in/api/v1/register-service/
Headers: {'Content-type': 'application/json'}
Payload
{
"key":"---Your Clickpost API KEY--",
"service_id":2
}
Response
{
"message": "SUCCESS",
"status_code": 200,
"success": true
}
Fields Explanation:
| Parameter | Type | Description |
|---|---|---|
| key (required) | character | this is the API Key provided to you |
| service_id (required) | Integer | this is the Integer id of service for which you want to register |
Service ID
| ID | Use |
|---|---|
| 1 | For placing orders on courier partner |
| 2 | For Tracking Shipments on Clickpost |
| 3 | For using Clickpost Recommendation Engine |
Register an AWB for tracking
POST request. URL:
https://www.clickpost.in/api/v2/tracking/awb-register/
Headers: {'Content-type': 'application/json'}
Sample Payload
{
"waybill": "ABCDRESDEFGHIJKL1257679",
"cp_id": 1,
"key": "42d42a34-ae09-4693-b20c-ae2624218a329",
"account_code": "Fedex Domestic",
"consumer_details": {
"name": "Prashant Gupta",
"phone": "8080808080",
"email": "support@clickpost.in"
},
"shipment_info": {
"item": "Shirt",
"order_type": "COD",
"invoice_value": 1000,
"reference_number": "123XYZ",
"length": 10,
"height": 10,
"weight": 10,
"breadth": 10,
"drop_pincode": "110019",
"pickup_pincode": "110017",
"delivery_type": "FORWARD",
"cod_amount": 1000.10,
"drop_address": "Roots hacker Home, R 28, Second Floor, Nehru Enclace, Opposite Nehru Place, New Delhi 110019",
"additional": {
"items": [
{
"sku": "XYZ1",
"description": "item1",
"quantity": 1,
"price": 200,
"images": "<Image URL>",
"additional": {
"length": 10,
"height": 10,
"breadth": 10,
"weight": 100
}
}
]
}
},
"additional": {
"order_date": "2017-02-14T18:00:00+05:30",
"ship_date": "2017-02-14T23:00:00+05:30"
}
}
Response
{
"meta": {
"message": "SUCCESS",
"status": 200,
"success": true
},
"result": {
"security_key": "530470b0-8ebd-40c3-9c9e-6ca6bf1d29b8",
"consumer_details": {
"id": 1
},
"shipment_info": {
"id": 1
},
"tracking_id": 1188264
}
}
Fields Explanation
Compulsory:
| Parameter | Type | Description |
|---|---|---|
| key (required) | character | this is the API Key |
| waybill (required) | character | this is/are comma separated waybill numbers for which the status is required |
| cp_id (required) | integer | courier_partner_id as specified on page 1 of this documentation |
| account_code (optional) | string | account code in case you have multiple accounts for same courier partner |
Optional:
consumer_details (optional): In case you want Clickpost to send notifications to your customers via mail / sms, please pass information in this object:
| Parameter | Type | Description |
|---|---|---|
| name | character (250 chars) | end customer name, who will receive the shipment, this will be used to personalize the SMS / email sent to the customer |
| phone_number | 10/11 characters | customer phone number on which SMS is to be sent. |
| character (150 chars) | Email address of the customer, on which email is to be sent. |
shipment_info (optional): shipment information for rich analytics on your data:
| Parameter | Type | Description |
|---|---|---|
| item | character (500 chars) | name of item sent to the customer |
| order_type | character | either COD or PREPAID |
| invoice_value | float | shipment invoice value |
| reference_number | character (len: 100) | order_id or reference number to be shared with end customer |
| length | integer | in cm |
| breadth | integer | in cm |
| height | integer | in cm |
| weight | integer | in grams |
| drop_pincode | character | 6 digit pincode of drop location |
| pickup_pincode | character | 6 digit pincode of pickup location |
| delivery_type | character | either FORWARD / RVP |
| cod_amount | float field | COD value to be collected from customer, float field |
| drop_address | character (500 chars) | drop address of the shipment |
| additional | object | optional field which can have additional information related to items like description, images for return management solution (easier for end customer to select which product to return) |
additional (optional): extra information about shipment used to power tracking page:
| Parameter | Type | Description |
|---|---|---|
| order_date | character | timestamp when the order was placed |
| ship_date | character | timestamp when order was ready to ship |
Un-Track an Order or Mark a shipment expired
You have to be registered for tracking service to use this api, if you have not, please check Registering for Tracking Service Section.
POST request. URL:
https://www.clickpost.in/api/v1/tracking/awb-unregister/
Headers: {'Content-type': 'application/json'}
Sample Payload
{
"cp_id": 1,
"waybill": "786000454820",
"key": "8341db95-a25d-4825-9b83-c62c20284b21"
}
Response
{
"meta": {
"success": true,
"status": 200,
"message": "SUCCESS"
},
"result": {
"awb": "786000454820"
}
}
Fields Explanation
Compulsory:
| Parameter | Type | Description |
|---|---|---|
| key (required) | character | this is the API Key |
| waybill (required) | character | this is/are comma separated waybill numbers for which the status is required |
| cp_id (required) | integer | courier_partner_id as specified on page 1 of this documentation |
Response Explanation:
- “meta” stores information about the API, success or failure
- success: true/false, true if the API worked fine, else false
- message: SUCCESS if everything is fine, else the error message c. status: 200, if the API data was fine, 400 in case of a bad request
- “result” is an array of records. Each record holds information of comma-separated waybill entered in the request parameter.
Tracking AWB Using Polling
URL
https://www.clickpost.in/api/v2/track-order/?username=testuser&key=2e9b19ac-8e1f- 41ac-a35b-4cd23f41ae17&waybill=3515341&cp_id=10
Headers: {'Content-type': 'application/json'}
Response
{
"meta": {
"message": "SUCCESS",
"status": 200,
"success": true
},
"result": {
"SF18399217NER": {
"latest_status": {
"clickpost_status_description": "Delivered",
"clickpost_status_code": 8,
"clickpost_status_bucket": 6,
"status": "Delivered successfully",
"location": "",
"remark": "Delivered successfully",
"timestamp": "2018-07-07 19:34:46"
},
"additional": {
"is_stuck": false,
"dest_hub_inscan": false,
"order_detail": [],
"edd": {
"min_sla": 2,
"max_sla": 5
}
},
"scans": [
{
"clickpost_status_description": "Delivered",
"clickpost_status_code": 8,
"clickpost_status_bucket": 6,
"status": "Delivered successfully",
"location": "",
"remark": "Delivered successfully",
"tracking_id": 12087859,
"timestamp": "2018-07-07 19:34:46",
"checkpoint_id": 163921399
},
{
"clickpost_status_description": "OutForDelivery",
"clickpost_status_code": 6,
"clickpost_status_bucket": 4,
"status": "Out for Delivery",
"location": "",
"remark": "Out for Delivery",
"tracking_id": 12087859,
"timestamp": "2018-07-07 08:53:01",
"checkpoint_id": 163496669
},
{
"clickpost_status_description": "InTransit",
"clickpost_status_code": 5,
"clickpost_status_bucket": 3,
"status": "Assigned to a Shadowfax Rider",
"location": "",
"remark": "Assigned to a Shadowfax Rider",
"tracking_id": 12087859,
"timestamp": "2018-07-07 08:52:51",
"checkpoint_id": 163496670
},
{
"clickpost_status_description": "InTransit",
"clickpost_status_code": 5,
"clickpost_status_bucket": 3,
"status": "Reached the nearest hub",
"location": "",
"remark": "Reached the nearest hub",
"tracking_id": 12087859,
"timestamp": "2018-07-07 08:02:08",
"checkpoint_id": 163496671
},
{
"clickpost_status_description": "OrderPlaced",
"clickpost_status_code": 1,
"clickpost_status_bucket": 1,
"status": "In Manifest",
"location": "GUNJAN ",
"remark": "In Manifest",
"tracking_id": 12087859,
"timestamp": "2018-07-07 02:47:21",
"checkpoint_id": 163419110
},
{
"clickpost_status_description": "InTransit",
"clickpost_status_code": 5,
"clickpost_status_bucket": 3,
"status": "Collected by Shadowfax",
"location": "GUNJAN ",
"remark": "Collected by Shadowfax",
"tracking_id": 12087859,
"timestamp": "2018-07-07 02:25:34",
"checkpoint_id": 163419111
},
{
"clickpost_status_description": "OrderPlaced",
"clickpost_status_code": 1,
"clickpost_status_bucket": 1,
"status": "Assigned to Shadowfax",
"location": "",
"remark": "Assigned to Shadowfax",
"tracking_id": 12087859,
"timestamp": "2018-07-06 05:41:13",
"checkpoint_id": 162947643
}
],
"valid": true
}
}
}
Package tracker API retrieves the historic statuses and the current status of the package.
The API is a HTTP GET request to:
https://www.clickpost.in/api/v2/track-order/
where output is json
Listed below are the parameters:
| Parameter | Type | Description |
|---|---|---|
| key (required) | character | this is the API Key |
| username (required) | character | user name, provided to you |
| waybill (required) | character | this is/are comma separated waybill numbers for which the status is required |
| cp_id (required) | integer | courier_partner_id as specified on page 1 of this documentation |
Response Explanation:
- “meta” stores information about the API, success or failure
- success: true/false, true if the API worked fine, else false
- message: SUCCESS if everything is fine, else the error message c. status: 200, if the API data was fine, 400 in case of a bad request
- “result” is an array of records. Each record holds information of comma-separated waybill entered in the request parameter.
- Each record has following objects:
- “valid”: (true / false) in case a wrong AWB / AWB which is not yet registered on Clickpost; is entered to track a shipment, “valid” field will be false. If the AWB is correct, “valid” will be true
- “waybill”: AWB provided in the API. Is the key of each object. The value is a dictionary storing information about shipment:
- scans: Stores all scans that happened for shipment. Has following keys:
- status: status of the shipment at that time
- remarks: remark given by courier partner
- location: location of shipment at the time of the scan
- timestamp: date/time in ISO format when the scan was done
- clickpost_status_code: clickpost generated status code for particular status. Clickpost has mapped various statuses of different courier companies into few status codes, which helps customers understand and take action on statuses in preemptive manner. (Explained on last page of this document)
- clickpost_status_description: description of clickpost_status_code (Specified on last page of this document)
- scans: Stores all scans that happened for shipment. Has following keys:
- lateststatus: Stores information about the latest status of shipment, has following fields:
- status: status of the shipment at that time
- remarks: remark given by courier partner
- location: location of shipment at the time of the scan
- timestamp: date/time in ISO format when the scan was done
- clickpost_status_code: clickpost generated status code for particular status. Clickpost has mapped various statuses of different courier companies into few status codes, which helps customers understand and take action on statuses in preemptive manner (Explained on last page of this document)
- clickpost_status_description: description of clickpost_status_code (Specified on last page of this document)
- clickpost_status_bucket: this is a consolidated id built on top of clickpost_status_codes, that can be used to show status to the customer on your track orders page. It has following distinct values:
| clickpost_status_bucket | Meaning | clickpost_status_code clubbed in the bucket |
|---|---|---|
| 1 | Order Placed by Customer | [1, 2, 3, 28, 25, 10] |
| 2 | Dispatched | [4] |
| 3 | In Transit | [5, 18, 19, 20] |
| 4 | Out For Delivery | [6] |
| 5 | Failed Delivery | [7, 9] |
| 6 | Delivered | [8] |
| 7 | Returned: When shipment is in return journey due to customer rejection | [11, 12, 13, 14, 15, 21, 26, 27] |
| 8 | Lost | [16] |
| 9 | Damaged | [17] |
6, 7, 8: These are terminal buckets in shipment journey
Tracking AWB Using Webhooks
Webhook Payload Header
{
"Content-Type": "application/json",
"webhook_key": "webhook_key_given_during_webhooks_register"
}
Webhook Payload
{
"waybill": "P0109276342",
"clickpost_status_code": 6,
"cp_id": 14,
"clickpost_status_description": "OutForDelivery",
"status": "O",
"location": "VASAI, MUMBAI",
"timestamp": "2017-08-02T13:23:02Z",
"remark": "Out For Delivery",
"additional": {
"latest_status": {
"clickpost_status_code": 6,
"location": "VASAI, MUMBAI",
"status": "O",
"clickpost_status_description": "OutForDelivery",
"timestamp": "2017-08-02T13:23:02Z",
"remark": "Out For Delivery"
}
}
}
NDR(Non delivery report) details in Webhook, send when the status_code = 9 (Failed Delivery)
{
"status": "When forward shipment is not accepted by end customer",
"remark": "Failed Delivery",
"waybill": "XYZABC",
"location": "Bengaluru_Koramangala_Dc (Karnataka)",
"timestamp": "2016-07-12T17:12:36.710",
"clickpost_status_code": 9,
"clickpost_status_description": "FailedDelivery",
"cp_id": 1,
"additional": {
"latest_status": {
"clickpost_status_code": 9,
"location": "Bengaluru_Koramangala_Dc (Karnataka)",
"status": "When forward shipment is not accepted by end customer",
"clickpost_status_description": "FailedDelivery",
"timestamp": "2016-07-12T17:12:36.710",
"remark": "Failed Delivery"
},
"ndr_status_code": 1,
"ndr_status_description": "Customer Unavailable"
}
}
Activating Webhooks:
- Visit Clickpost dashboard: Settings Tab on the left and Click notification section
- Select webhooks and activate Selected webhooks configuration or All Webhooks configuration as per your need
Webhook data POST on Client Server for all events:
Every time courier partner updates tracking of the shipment, We will post data to your server using the url you registered while registering for webhooks.
Payload Explanation:
- waybill: AWB number for which data is posted.
- status: status of the shipment at that time
- remarks: remark given by courier partner
- location: location of shipment at the time of the scan
- timestamp: date/time in IST format when the scan was done
- clickpost_status_code: clickpost generated status code for particular status. Clickpost has mapped various statuses of different courier companies into few status codes, which helps customers understand and take action on statuses in preemptive manner. (Explained in next section)
- clickpost_status_description: description of clickpost_status_code (Specified on next page)
Webhook data POST on Client Server for selected events:
In case customer wants to recieve notifications only for certain events, Clickpost provides funtionality for the same.
If customer opts for this service, we add: “notification_event_id” key in additional object of the payload. This will inform you the current status of shipment.
Possible values:
- Out For Pickup
- Shipped
- Out For Delivery
- Failed Delivery
- Delivered
- RTO
- RTO-Delivered
Please see the sample payload on the right:
Selected event subscribed webhook: Failed delivery Payload
{
"remark": "Customer Cancelled the order",
"waybill": "420714276042",
"clickpost_status_description": "FailedDelivery",
"timestamp": "2018-08-06T14:48:57.002000Z",
"cp_id": 4,
"status": "Pending",
"clickpost_status_code": 9,
"location": "Kayamkulam_Bhrnikvu_D (Kerala)",
"additional": {
"notification_event_id": 4,
"ndr_status_description": "No attempt",
"ndr_status_code": 4,
"latest_status": {
"remark": "Customer Cancelled the order",
"timestamp": "2018-08-06T14:48:57.002000Z",
"clickpost_status_description": "FailedDelivery",
"status": "Pending",
"clickpost_status_code": 9,
"location": "Kayamkulam_Bhrnikvu_D (Kerala)"
}
}
}
Selected event subscribed webhook: Delivered Payload
{
"remark": "Delivered to consignee",
"waybill": "420714276075",
"clickpost_status_description": "Delivered",
"timestamp": "2018-08-06T15:00:32.002000Z",
"cp_id": 4,
"status": "Delivered",
"clickpost_status_code": 8,
"location": "Udaipur_DC (Rajasthan)",
"additional": {
"notification_event_id": 5,
"latest_status": {
"remark": "Delivered to consignee",
"timestamp": "2018-08-06T15:00:32.002000Z",
"clickpost_status_description": "Delivered",
"status": "Delivered",
"clickpost_status_code": 8,
"location": "Udaipur_DC (Rajasthan)"
}
}
}
Important Notes and special data in Webhooks (Examples are present on the right):
- Webhooks do not guarantee the order of data send to Client servers. latest_status indicates the latest status for the shipment at the time when the webhook is sent. This is sent with all webhooks
- In case of NuvoEx Reverse Pickup: doorstep Quality Check order, additional has dsqc object at the time of pickup cancelled (clickpost_status_code = 10) and pickedup (clickpost_status_code = 4)
- In case of Failed Delivery, Clickpost unified NDR status code and NDR status description is sent in additional
- Please make your API end point idempotent
- Since webhooks are transactional in nature, To insure minimal API data loss, we have retries in place if we do not get http 200 response from your server
- If you opt for selected events webhook notification, in case clickpost receives multiple notification from courier partner at the same time, only the latest notification will be sent to you
NDR Status Codes
| ndr_status_code | ndr_status_description |
|---|---|
| 0 | “Unknown Exception” |
| 1 | “Customer Unavailable” |
| 2 | “Rejected by Customer” |
| 3 | “Delivery Rescheduled” |
| 4 | “No Attempt” |
| 5 | “Customer Unreachable” |
| 6 | “Address Issue” |
| 7 | “Payment Issue” |
| 8 | “Out Of Delivery Area” |
| 9 | “Order Already Cancelled” |
| 10 | “Self Collect” |
| 11 | “Shipment Seized By Customer” |
Clickpost recommends that the mapping of NDR be done strictly on ndr_status_code and not on ndr_status_description
Testing Webhook
Test Webhook URL
https://www.clickpost.in/api/v1/test_webhook?key=<YOUR_API_KEY>
Test Webhook Payload
{
"test_url": "http://www.clickpost.in/",
"test_data": {
"status": "When forward shipment is not accepted by end customer",
"remark": "Failed Delivery",
"waybill": "XYZABC",
"location": "Bengaluru_Koramangala_Dc (Karnataka)",
"timestamp": "2016-07-12T17:12:36.710",
"clickpost_status_code": 9,
"clickpost_status_description": "FailedDelivery",
"cp_id": 1,
"additional": {
"latest_status": {
"clickpost_status_code": 9,
"location": "Bengaluru_Koramangala_Dc (Karnataka)",
"status": "When forward shipment is not accepted by end customer",
"clickpost_status_description": "FailedDelivery",
"timestamp": "2016-07-12T17:12:36.710",
"remark": "Failed Delivery"
},
"ndr_status_code": 1,
"ndr_status_description": "Customer Unavailable"
}
}
}
You can test the webhooks by making a POST request on the following URL:
https://www.clickpost.in/api/v1/test_webhook?key=<YOUR_API_KEY>
Where test_url is your server URL where you want to test the webhook data.
This will send sample payload as specified in test_data with Headers on the server mentioned in test_url.
Cancel Shipment API
URL to hit:
https://www.clickpost.in/api/v1/cancel-order/?username=test&key=42d42a34-ae09-4693- b20c-ae2624&waybill=782715732348&cp_id=8
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you) Response:
Example: POST Body (Cancel Order)
{
"meta": {
"message": "8159:Shipment Delete was requested for a tracking
number already in a deleted state.",
"success": false,
"status": 400
}
}
Cancel API allows you to cancel a shipment for which the order has been created.
The API is a HTTP GET request to: https://www.clickpost.in/api/v1/cancel-order/ where output is json
Listed below are the parameters:
URL parameters:
- username: User name provided to you.
- key: API key provided to you.
- waybill: waybill, which needs to be cancelled
- cp_id: Courier Partner ID of the courier from which shipment was dispatched. List: http://track.clickpost.in/courier_partner
Response Explanation:
Response will have meta tag which explains about the status of the shipment:
- message:
SUCCESSin case the Shipment is deleted successfully, else the error message provided by courier partner. - success: true if order is deleted successfully, else false
- status: 200 if API works fine, 400 in case of bad request
Pincode Serviceability API
URL to hit
https://www.clickpost.in/api/v1/serviceability_api/?username=test&key=42d42a34-ae09-4693-%20b20c-ae2624
(username and key needs to be replaced with the key provided to you)
Example(POST Body)
[{
"optional": {
"length": 10,
"breadth": 10,
"height": 10,
"invoice_value": 1245,
"weight": 10,
"cp_id": 3,
"service_type": "FORWARD/RVP/EXCHANGE"
},
"drop_pincode": "110020",
"pickup_pincode": "122002"
}]
Response
{
"result": [
{
"cp_id": 3,
"serviceable": {
"PREPAID": false,
"COD": false
},
"comitted_sla": null,
"account_code": "Sample_Ecom_1",
"shipping_charge": {
"PREPAID": null,
"COD": null
}
},
{
"cp_id": 3,
"serviceable": {
"PREPAID": false,
"COD": false
},
"comitted_sla": null,
"account_code": "Sample_Ecom_2",
"shipping_charge": {
"PREPAID": null,
"COD": null
}
}
],
"meta": {
"success": true,
"status": 200,
"message": "SUCCESS"
}
}
Serviceability api checks if pickup and drop pincodes are serviceabile or not, shipping charges for the shipment and turn around time for the delivery. It accepts the shipment dimension fields as additional parameters. Courier company id can be passed to check the serviceability for a specific courier company.
It’s a POST request as follows
URL:
https://www.clickpost.in/api/v1/serviceability_api/
Headers: {‘Content-type’: 'application/json’}
URL Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | character | API key provided to you |
| username | character | username provided to you |
POST Parameters:
Format: JSON
Compulsory Fields
Payload is a list of json objects each of which have following fields:
| Parameter | Type | Description |
|---|---|---|
| pickup_pincode | integer | pincode of pickup address |
| drop_pincode | integer | pincode of drop address |
Optional Fields
| Parameter | Type | Description |
|---|---|---|
| invoice_value | double | invoice value of the shipment |
| order_type | character | COD/PREPAID |
| weight | integer | weight of the shipment |
| length | integer | length of the shipment |
| breadth | integer | breadth of the shipment |
| height | integer | height of the shipment |
| cp_id | integer | clickpost courier comapny id |
| service_type | character | Any one of FORWARD/RVP/EXCHANGE, if service_type param is not passed, then default is FORWARD. |
Response explanation:
Response object has two parts:
- meta: stores information about the API, success or failure
- success: true/false, tells whether the order was created or not
- message: SUCCESS in case request was successfully processed by clickpost, else returns error message.
- status:
- 200 if the order is created successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result:
- serviceable: JSON object which stores following two fields:
- COD: Values: true: if the pincode is COD serviceable else false
- PREPAID: Values: true: if the pincode is COD serviceable else false
- commited_sla: average commited SLA by courier partner (based on your contract with courier partner) for the shipment if dispatched today. (integer field)
- account_code: Account code for which the details are given in the result.
- shipping_charges: Shipping charges for the delivery of the shipment.
- serviceable: JSON object which stores following two fields:
Expected Date of Delivery API
URL to hit
https://www.clickpost.in//api/v1/predicted_sla_api/?username=test&key=42d42a34-ae09-4693-%20b20c-ae2624
(username and key needs to be replaced with the key provided to you)
Example(POST Body with courier partner provided)
[
{
"pickup_pincode": "600040",
"drop_pincode": "421504",
"optional" : {
"cp_id" :5,
"awb": "ABCD12345"
}
}
]
Response
{
"meta": {
"status": 200,
"success": true,
"message": "SUCCESS"
},
"result": [
{
"predicted_sla_min": 1,
"min_sla_cp_id": 5,
"predicted_sla_max": 1,
"all_map": {
"5": [
1,
1
]
}
}
]
}
Example(POST Body across all courier partners)
[
{
"pickup_pincode": "600040",
"drop_pincode": "421504"
}
]
Response
{
"meta": {
"status": 200,
"success": true,
"message": "SUCCESS"
},
"result": [
{
"predicted_sla_min": 1,
"min_sla_cp_id": 5,
"predicted_sla_max": 1,
"all_map": {
"3": [
2,
3
],
"4": [
3,
6
],
"5": [
1,
1
],
"6": [
1,
1
],
"14": [
2,
3
],
"15": [
1,
1
],
"1001": [
1,
1
]
}
}
]
}
The expected date of delivery API computes the minimum/maximum time range, a shipment lifecycle may take between the pickup and drop pincode using our predictive machine learning algorithm. By default, it computes the range for all courier companies available and gives the courier partner id which might deliver the shipment fastest. Optional courier comapny id can be passed to see the range for a specific courier partner; errors/warnings will be highlighted in the response.
It’s a POST request as follows
URL:
https://www.clickpost.in/api/v1/predicted_sla_api/
Headers: {‘Content-type’: 'application/json’}
URL Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | character | API key provided to you |
| username | character | username provided to you |
POST Parameters:
Format: JSON
Compulsory Fields
Payload is a list of json objects each of which have following fields:
| Parameter | Type | Description |
|---|---|---|
| pickup_pincode | integer | pincode of pickup address |
| drop_pincode | integer | pincode of drop address |
Optional Fields
| Parameter | Type | Description |
|---|---|---|
| cp_id | integer | courier partner id |
| awb | char | awb for which expected delivery date is to be calculated |
List of courier partners is present at: http://track.clickpost.in/courier_partner
Response explanation:
Response object has two parts:
- meta: stores information about the API, success or failure
- success: true/false, tells whether the request was processed successfully by Clickpost
- message: SUCCESS in case request was successfully processed by Clickpost, else returns error message.
- status:
- 200 if the request is processed successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result:
- predicted_sla_min: minimum sla in days predicted by Clickpost between the given pin codes
- predicted_sla_max: maximum sla in days predicted by Clickpost between the given pin codes
- min_sla_cp_id: courier partner id corresponding to the smallest sla of shipment between the pin codes given
- all_map: contains [min, max] values for all courier partners serviced by Clickpost
Pickup Request API
URL to hit:
https://www.clickpost.in/api/v1/create-pickup/?username=test&key=42d42a34-ae09-4693- b20c-ae
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you) POST Body:
Example: POST Body (Pickup Request)
{
"pickup_date": "2018-10-23T15:30:39+05:30",
"courier_partner": 1,
"items": "3 Carton boxes, 20 KGs",
"pickup_pincode": 560037,
"pickup_email": "Test@pickupwarehousemail.com",
"pickup_phone": 8080808080,
"pickup_name": "Warehouse Pickup POC",
"pickup_city": "Bengaluru Urban",
"pickup_state": "KARNATAKA",
"pickup_address": "Test Pickup Warehouse Address, Pickup Locality, ",
"account_code": "BluedartAIR"
}
The Pickup Request API allows you to place pickup request for courier partners and obtain confirmation for the same.
Please note, in case of any validation failure - order will not get created.
The API is a HTTP POST request to:
https://www.clickpost.in/api/v1/create-pickup/ where output format is json.
Listed below are the parameters:
URL parameters:
| Parameter | Type | Description |
|---|---|---|
| username | character | user name provided to you |
| key | character | API key provided to you |
POST Parameters:
Format: JSON
Compulsory Fields:
| Parameter | Type | Description |
|---|---|---|
| pickup_date | character | ISO datetime field example: 2015-03-31T12:00:00Z |
| courier_partner | integer | ID of courier partner for which the pickup request needs to be placed. List at : http://track.clickpost.in/courier_partner |
| items | character | description of item that needs to be placed. Max length: 200 chars |
| pickup_address | character | Address of pickup location |
| pickup_name | character | Contact person for the pickup |
| pickup_email | character | email contact of the pickup location |
| pickup_pincode | integer | pincode of pickup location |
| pickup_phone | integer | contact number of pickup location, 10/11 digit number |
| pickup_city | character | name of pickup city |
| pickup_state | character | name of pickup state |
Response
{
"meta": {
"message": "SUCCESS",
"success": true,
"status": 200
},
"result": {
"location": "DELKL",
"confirmation_number": "6"
}
}
Response Explanation:
Response will have meta tag which explains about the status of the API and result which provides pickup details. In meta tag:
- message: SUCCESS if the pickup request is placed successfully, error message otherwise
- success: true if pickup request is placed successfully, else false
- status: 200 if pickup request is placed successfully, 400 in case of bad request
In result tag:
- location: ID of pickup location shared by courier partner
- confirmation_number: pickup confirmation number
Result tag will be present in request only if the meta tag contains success : true.
Tracking Page / Widget
To integrate with your website:
- Place widget script in your webpage.
- Place widget HTML code in your webpage.
Note: It’s better to move widget script to as low in the web page as possible.
Tracking Page / Widget is designed to provide exhaustive tracking to end user.
The widget/page has following features:
- End to end shipment tracking. Incase you want the tracking page to show Order Placed and Ready to Ship milestone as well, please pass order_date and ship_date in AWB-register API.
- Failed delivery feedback from customer: During a failed delivery by courier partner, customer can enter his input/concern over a form which will be shared with you as a report daily or same can be fetched via API (Customer Feedback API)
- In case you want customer to request a delivery preference any time before an attempt for delivery is made, please contact our team to enable the feature. Feedback of the same will be available as for point 2.
- Design language of the page is customisable as per your website theme. Our team can help you in designing the page.
JS to be included:
<script type="text/javascript" src="http://track.clickpost.in/clickpost-widget-1.0.3.js"></script>
Tracking widget using AWB number and Courier Partner ID
Fields Explanation:
| Parameter | Type | Description |
|---|---|---|
| id | string | Your Waybill number |
| data-cpId | string | Your Courier Partner Id |
<div id="1234567890" class="tracking-widget" data-cpId="11"></div>
Tracking widget using Reference Number (Order ID)
Fields Explanation:
| Parameter | Type | Description |
|---|---|---|
| id | string | Your order reference number |
| data-username | string | username provided to you |
| data-key | string | API Key provided to you |
<div id="1234567890" class="tracking-widget" data-key="123-456-7890" data-username="xyz"></div>
Note: No need to add more than one script for multiple tracking widgets in a page.
Customer Feedback API
URL to hit
https://www.clickpost.in/api/v1/ndr_user_feedback/?username=test&key=42d42a34-ae09-4693-%20b20c-ae2624&start_date=1509529561&end_date=1512121581
(username and key needs to be replaced with the key provided to you)
Example - GET Request
https://www.clickpost.in/api/v1/ndr_user_feedback/?username=test&key=42d42a34-ae09-4693-%20b20c-ae2624&start_date=1509529561&end_date=1512121581
Response
{
"result": [{
"phone": null,
"api_data_push": null,
"created_at": "2018-05-20T07:44:24.704183Z",
"type": "CUSTOMER_FEED",
"landmark": null,
"comment": "Shipment Delayed",
"clickpost_status_code": 9,
"awb": "SF16384627NER",
"preferred_time": null,
"preferred_date": null,
"address": null,
"clickpost_status_description": "Delivery Failed",
"reference_number": "Order-ID",
"additional": {
"internal_cst_responded": true,
"internal_username": "netmeds",
"internal_comment": "Test"
}
}],
"meta": {
"meta": {
"message": "Success",
"success": true,
"status": 200
}
}
}
This api gives the list of feedback submitted through clickpost tracking page from start date to end date; errors/warnings will be highlighted in the response.
It’s a GET request as follows
URL:
https://www.clickpost.in//api/v1/ndr_user_feedback/
Headers: {‘Content-type’: 'application/json’}
URL Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | character | API key provided to you |
| username | character | username provided to you |
GET Parameters:
Format: JSON
Compulsory Fields
| Parameter | Type | Description |
|---|---|---|
| start_date | long | UTC epoch start time |
| start_date | long | UTC epoch end time |
Response explanation:
Response object has two parts:
- meta: stores information about the API, success or failure
- success: true/false, tells whether the request was processed successfully by Clickpost
- message: SUCCESS in case request was successfully processed by Clickpost, else returns error message.
- status:
- 200 if the request is processed successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result:
- address: New Address change by end user
- comment: comment/description of change by end user
- preferred_time: Preferred time of delivery
- preferred_date: prefered date of delivery
- landmark: landmark for the address
- created_at: timestamp when the user made request for this change
- awb: awb number for which change is requested
- phone: new phone number for delivery
- clickpost_status_code: shipment status code when customer entered the feedback
- clickpost_status_description: shipment status description when customer entered the feedback
- reference_number: reference_number passed to Clickpost
- type: either CLIENT_OPS_FEED or CUSTOMER_FEED
- api_data_push: if the data is pushed via api to courier company or not, null means we did not try to push, true is successfully pushed and false if failed to push.
- additional: internal_cst_responded: in case of CLIENT_OPS_FEED (Feedback by your operations team), if operation team has word with customer, they will mark the same on NDR Management section of the dashboard. Possible values: True / False
- additional: internal_comment: in case of CLIENT_OPS_FEED (Feedback by your operations team), if operation team enters any internal comment. This is a string field
- additional: internal_username: in case of CLIENT_OPS_FEED (Feedback by your operations team), if there are multiple users, username of employee updating the remark will populate here
NDR Action Update API
URL to hit
https://www.clickpost.in/api/v1/ndr/update/?username=test&key=42d42a34-ae09-4693-%20b20c-ae2624&cp_id=4
(username and key needs to be replaced with the key provided to you)
Example - POST Request
[
{
"waybill": "1823821",
"act": "DEFER_DLV",
"action_data": {
"deferred_date": "2017-12-28"
}
},
{
"waybill": "3278213",
"act": "EDIT_DETAILS",
"action_data": {
"name": "name1",
"add": "add1",
"phone": "2132341412"
}
},
{
"waybill": "278382",
"act": "RE-ATTEMPT"
},
{
"waybill": "1278728",
"act": "RE-ATTEMPT"
}
]
Response
{
"result": {
"ndr_update_status": [
{
"cp_response": "UPL15970567163944112616",
"status": true,
"awb": "1823821"
},
{
"cp_response": "UPL15970567163944112616",
"status": true,
"awb": "3278213"
},
{
"cp_response": "UPL15970567163944112616",
"status": true,
"awb": "278382"
},
{
"cp_response": "in valid awb and action not supported",
"status": false,
"awb": "1278728"
}
]
},
"meta": {
"message": "Success",
"success": true,
"status": 200
}
}
This api instructs the courier company to take action on a awb. Only Four actions supported (DEFER_DLV, EDIT_DETAILS, RE-ATTEMPT, INITIATE_RTO); errors/warnings will be highlighted in the response.
It’s a POST request as follows
Headers: {‘Content-type’: 'application/json’}
URL Parameters:
| Parameter | Type | Description |
|---|---|---|
| key | character | API key provided to you |
| username | character | username provided to you |
| cp_id | integer | courier company id provided by clickpost |
List of courier partners is present at: http://track.clickpost.in/courier_partner
POST Parameters:
Format: JSON
Compulsory Fields
| Parameter | Type | Description |
|---|---|---|
| waybill | stiring | awb number for ndr action update |
| act | long | action to take (DEFER_DLV, EDIT_DETAILS, RE-ATTEMPT) |
Optional Fields
| Parameter | Type | Description |
|---|---|---|
| action_data->deferred_date | character | [DEFER_DLV] Deferred date for reattempt in (YYYY-MM-DD) format |
| action_data->name | character | [EDIT_DETAILS] Name of person to handover the shipment |
| action_data->add | character | [EDIT_DETAILS] Address where shipment need to be delivered |
| action_data->phone | character | [EDIT_DETAILS] Phone no of the persion to contact for delivery |
[RE-ATTEMPT] : No need to pass action_data
Response explanation:
Response object has two parts:
- meta: stores information about the API, success or failure
- success: true/false, tells whether the request was processed successfully by Clickpost
- message: SUCCESS in case request was successfully processed by Clickpost, else returns error message.
- status:
- 200 if the request is processed successfully,
- 400 if there is a bad request encountered: errors will be present in “message”
- result:
- ndr_update_status: contains array of ndr update responses for each awb number
- ndr_update_status->cp_response: courier company reference number for the action requested
- ndr_update_status->status: true/false based on if ndr action is updated or not
- ndr_update_status->awb: awb number corresponding to ndr update action
Track Return Order
Tracking AWB Using Webhooks
Webhook Payload Header
{
"Content-Type": "application/json",
"webhook_key": "webhook_key_given_during_webhooks_register"
}
Webhook Payload
{
"waybill": "",
"clickpost_status_code": 101,
"cp_id": -1,
"clickpost_status_description": "Return Order Placed",
"status": "O",
"location": "VASAI, MUMBAI",
"timestamp": "2017-08-02T13:23:02Z",
"remark": "Return Order Placed",
"additional": {
"self_shipped" : False,
"is_rvp":True,
"forward_awb":"sample_forward_awb",
"forward_reference_number":"sample_forward_reference",
"latest_status": {
"clickpost_status_code": 101,
"location": "",
"status": "O",
"clickpost_status_description": "Return Order Placed",
"timestamp": "2017-08-02T13:23:02Z",
"remark": "Return Order Placed"
}
}
}
Activating Webhooks:
- Visit Clickpost dashboard: Settings Tab on the left and Click notification section
- Select webhooks and activate Selected webhooks configuration or All Webhooks configuration as per your need
Payload Explanation:
- waybill: AWB number for which data is posted (Will be blank for return order placed).
- status: status of the shipment at that time
- remarks: remark given by courier partner
- location: location of shipment at the time of the scan
- timestamp: date/time in IST format when the scan was done
- clickpost_status_code: clickpost generated status code for particular status. Clickpost has mapped various statuses of different courier companies into few status codes, which helps customers understand and take action on statuses in preemptive manner.
- clickpost_status_description: description of clickpost_status_code
- is_rvp inside additional object tells the payload is for reverse orders. forward_awb field contain the forward awb number for which return order has been placed and forward_reference_number will have the corresponding reference number.
- waybill number will be blank as order is not yet created on courier company (not manifested yet)
- clickpost_status_code will have 101 value which is Return Order Placed.
- self_shipped: Either True or False depending upon how the return shipment is shipped, if shipped by customer, then self_shipped is True else False.
Webhook data POST on Client Server for selected events:
In case customer wants to recieve notifications only for certain events, Clickpost provides funtionality for the same.
If customer opts for this service, we add: “notification_event_id” key in additional object of the payload. This will inform you the current status of shipment. For return (Return Request Placed) this field’s value will be 11
Important Notes and special data in Webhooks (Examples are present on the right):
- Webhooks do not guarantee the order of data send to Client servers. latest_status indicates the latest status for the shipment at the time when the webhook is sent. This is sent with all webhooks
- Please make your API end point idempotent
- Since webhooks are transactional in nature, To insure minimal API data loss, we have retries in place if we do not get http 200 response from your server
- If you opt for selected events webhook notification, in case clickpost receives multiple notification from courier partner at the same time, only the latest notification will be sent to you
Testing Webhook
Test Webhook URL
https://www.clickpost.in/api/v1/test_webhook?key=<YOUR_API_KEY>
Test Webhook Payload
{
"test_url": "http://www.clickpost.in/",
"test_data": {
"status": "Return Order Placed",
"remark": "Return Order Placed",
"waybill": "",
"location": "",
"timestamp": "2016-07-12T17:12:36.710",
"clickpost_status_code": 101,
"clickpost_status_description": "Return Order Placed",
"cp_id": 1,
"additional": {
"is_rvp":True,
"forward_awb":"sample_forward_awb",
"forward_reference_number":"sample_forward_reference",
"latest_status": {
"clickpost_status_code": 101,
"location": "",
"status": "Return Order Placed",
"clickpost_status_description": "Return Order Placed",
"timestamp": "2016-07-12T17:12:36.710",
"remark": "Return Order Placed"
}
}
}
}
You can test the webhooks by making a POST request on the following URL:
https://www.clickpost.in/api/v1/test_webhook?key=<YOUR_API_KEY>
Where test_url is your server URL where you want to test the webhook data.
Tracking Status Codes
| clickpost_status_code | clickpost_status_description | Meaning |
|---|---|---|
| 1 | ORDER_PLACED | ‘Order Has Been Placed / Manifested on Courier Partner’ |
| 2 | PICKUP_PENDING | 'Pickup Pending’ |
| 3 | PICKUP_CANCELLED | 'Pickup Cancelled’ |
| 4 | PICKED_UP | 'Pickup Has Been Done’ |
| 5 | INTRANSIT | 'In Transit’ |
| 6 | OUT_FOR_DELIVERY | 'Shipment Out For Delivery’ |
| 7 | NOT_SERVICEABLE | 'Area For Delivery Is Not Servicable’ |
| 8 | DELIVERED | 'Shipment Delivered’ |
| 9 | FAILED_DELIVERY | 'Delivery Failed’ |
| 10 | CANCELLED_ORDER | 'Order Has Been Cancelled’ |
| 11 | RTO_REQUESTED | 'Rto For Shipment has been Requested’ |
| 12 | RTO | 'Marked As Return’ |
| 13 | RTO_OUT_FOR_DELIVERY | 'Shipment Is Out For Delivery For RTO’ |
| 14 | RTO_DELIVERED | 'RTO Delivered’ |
| 15 | RTO_FAILED | 'RTO Failed’ |
| 16 | LOST | 'Shipment is Lost’ |
| 17 | DAMAGED | 'Shipment is damaged’ |
| 18 | SHIPMENT_DELAYED | 'Shipment Is Delayed Or Misroute’ |
| 19 | CONTACT_CUSTOMER_CARE | 'Contact To The Customer Care’ |
| 20 | SHIPMENT_HELD | 'Shipment Is being held’ |
| 21 | RTO_INTRANSIT | 'RTO In Transit’ |
| 25 | OUT_FOR_PICKUP | 'Shipment Out For Pickup’ (Important in Marketplace / RVP pickups) |
| 26 | RTO_CONTACT_CUSTOMER_CARE | 'RTO Contact Customer Care’ |
| 27 | RTO_SHIPMENT_DELAY | 'RTO Shipment Delayed’ |
| 28 | Awb Registered | 'AWB registered on Clickpost’ |
Status flow diagram is available at: http://bit.ly/status_flow
It is strongly recommended to use the clickpost_status_code to apply any logic on unified statuses.
Error Codes
The Clickpost API uses the following error codes:
| Server Response Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 406 | Not Acceptable |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
| 503 | Service Unavailable |
| 504 | Server unable to serve the request, please retry |
| Clickpost Service Error Code | Meaning |
|---|---|
| 301 | Authentication Failed: Invalid Token or API Key |
| 302 | Invalid Courier Partner Id with Field cp_id |
| 303 | waybill already registered |
| 304 | Already Registered For Service |
| 306 | You are not Registered To Use this service, Please Register |
| 316 | You Dont Have Credentials For The Courier Partner |
| 320 | This service is not subscribed by you |
| 324 | You Are Using Invalid Credential For Courier Partner, Please Update |
| 325 | Status You Are Trying to update is invalid for our systems, Contact to tech@clickpost.in |
| 326 | Invalid Tracking Id |
| 328 | Invalid POST data |
| 330 | waybill does not exist |
| 351 | No account exist |
| 352 | Multiple Account exist |
| 353 | Inactive account |
| 354 | Unhandled CP error |
| 355 | Vendor code not found |
| 422 | Invalid Entity |
| Order Creation Error Code | Meaning |
|---|---|
| 307 | You have entered invalid Order Type |
| 308 | You have entered invalid Order priority |
| 309 | Invalid Delivery Type |
| 310 | RVP reason is missing |
| 311 | Invalid Courier Partner For RVP |
| 312 | Items Data is missing from order details |
| 313 | Invalid Format of items for Order data |
| 314 | Invalid Format Of Order Data |
| 315 | Invalid Cod Value |
| 319 | Error In Order Placing To Courier Partner |
| 321 | Awb Number Does not exist in system for courier partner |
| 322 | Internal Server Error In Courier Partners Server, Try Again |
| 323 | You have Already placed this order |
| Clickpost Webhook Error Code | Meaning |
|---|---|
| 305 | Webhook already Registered for the user |
| 327 | Webhook not registered for the user |
| Order Cancellation Error Code | Meaning |
|---|---|
| 600 | Order already cancelled |
| 350 | Order Cancellation Error from Courier Partner Server |