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).
- Whatsapp Optin-Optout: In case customer sends whatsapp optout communication to you, you can update the same in Clickpost using this API
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,
"additional": {
"custom_fields": [{
"key": "ptl_or_ftl",
"value": "PTL"
}, {
"key": "truck_size",
"value": "14 feet"
}]
}
}]
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 | character | pincode of pickup address |
| drop_pincode | character | 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 |
| additional | JSON object | custom parameters in the API request |
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",
"security_key": "560fee51-1af3-4d1d-a6e8-0149b0868d38",
"sort_code": "ABC/HYG/TEX/LUV"
}
}
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,
"cat": "electronics",
"sub_cat": "tv",
"color": "Red",
"serial_no": "SRN1237890000",
"size": "7",
"qc_rules": [
{
"question": "Is product colour as per description ?",
"is_mandatory": 1,
"value": "Red"
},
{
"question": "Is product size as per description ?",
"is_mandatory": 1,
"value": "7"
}
],
"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",
"qc_type": "doorstep",
"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 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 (only for shadowfax reverse with qc_type: doorstep) |
| 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 (only for shadowfax reverse with qc_type: doorstep) |
| color | character | color of the item to be picked (only for shadowfax reverse with qc_type: doorstep) |
| serial_no | character | serial_no of the item to be picked (only for shadowfax reverse with qc_type: doorstep) |
| size | character | size of the item to be picked (only for shadowfax reverse with qc_type: doorstep) |
| qc_rules | json array | questions to be asked by pickup boy (only for shadowfax reverse with qc_type: doorstep) |
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)
- security_key: All orders are allocated a security key, please store this security key in your system (36 char)
- sort_code: for certain logistics partners, a sort_code is passed in API response that you can consume if you generate the shipping label at your end. For courier partners where this is not needed, it will have null value (max 20 char) 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",
"pickup_lat": "10.01",
"pickup_long": "10.00"
},
"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",
"drop_email": "support@clickpost.in",
"drop_lat": "10.01",
"drop_long": "10.00"
},
"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",
"quantity": 1,
"sku": "XYZ1",
"additional": {
"length": 10,
"height": 10,
"breadth": 10,
"weight": 100,
"images": "http://sample-file1.jpg,http://sample-file2.jpg",
"return_days": 2
}
}
],
"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"
},
"reseller_info": {
"name": "Clickpost Support",
"phone": "8080808080"
},
"awb_number": "43062728295",
"delivery_type": "FORWARD",
"async": false,
"gst_number" : "21313",
"account_code": "<account_code generated via clickpost dashboard>",
"from_wh": "From Warehouse",
"to_wh": "To Warehouse",
"channel_name": "Channel Name: In case you have different channels to receive orders",
"order_date": "YYYY-MM-DD",
"enable_whatsapp": false, # Useful for whatsapp communication
"is_fragile": true,
"is_dangerous": true,
"order_id": "Order ID of the shipment"
}
}
Response
{
"meta": {
"message": "Order Placed Successfully",
"status": 200,
"success": true
},
"result": {
"courier_partner_id": 1,
"courier_name": "Fedex",
"sort_code": null,
"security_key": "560fee51-1af3-4d1d-a6e8-0149b0868d38",
"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",
"pickup_lat": "10.01",
"pickup_long": "10.00"
},
"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",
"drop_email": "support@clickpost.in",
"drop_lat": "10.01",
"drop_long": "10.00"
},
"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",
"from_wh": "From Warehouse",
"to_wh": "To Warehouse",
"channel_name": "Channel Name: In case you have different channels to receive orders",
"order_date": "YYYY-MM-DD",
"is_fragile": true,
"is_dangerous": true,
"order_id": "order ID of the shipment"
}
}
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 |
| pickup_lat | character | [optional] latitude of pickup location, required for Hyperlocal courier partners |
| pickup_long | character | [optional] longitude of pickup location, required for Hyperlocal courier partners |
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 | email of the customer |
| drop_lat | character | [optional] latitude of drop location, required for Hyperlocal courier partners |
| drop_long | character | [optional] longitude of drop location, required for Hyperlocal courier partners |
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. For Delhivery this field is passed in the API field ‘pickup_location[“name”]’. For XpressBees, this field is passed in their API field “PickupVendorCode”. |
| is_fragile | boolean | true if shipment is fragile. Default false. [Currently used only for eKart APIs] |
| is_dangerous | boolean | true if shipment is dangerous/liquid. Default false. [Currently used only for eKart APIs] |
| order_id | character [50 characters] | order ID of the shipment |
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. (max 20 char)
- security_key: All orders are allocated a security key, please store this security key in your system (36 char)
- courier_partner_id: Clickpost courier partner ID for the order for which the AWB was generated
- courier_name: Name of courier. For aggregators like Shiprocket, this field will have the courier name on which Shiprocket generated the 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",
"pickup_lat": "10.01",
"pickup_long": "10.00"
},
"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",
"drop_email": "support@clickpost.in",
"drop_lat": "10.01",
"drop_long": "10.00"
},
"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",
"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"
],
"cat": "electronics",
"sub_cat": "tv",
"color": "Red",
"serial_no": "SRN1237890000",
"size": "7",
"qc_rules": [{
"question": "Is product colour as per description ?",
"is_mandatory": 1,
"value": "Red"
},
{
"question": "Is product size as per description ?",
"is_mandatory": 1,
"value": "7"
}],
"additional": {
"length": 10,
"height": 10,
"breadth": 10,
"weight": 100
}
}
],
"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",
"qc_type": "doorstep",
"async": false,
"account_code": "ecom reverse",
"from_wh": "From Warehouse",
"to_wh": "To Warehouse",
"channel_name": "Channel Name: In case you have different channels to receive orders",
"order_date": "YYYY-MM-DD",
"order_id": "order ID of the shipment"
}
}
- 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 (only for shadowfax reverse with qc_type: doorstep) |
| 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 (only for shadowfax reverse with qc_type: doorstep) |
| color | character | color of the item to be picked (only for shadowfax reverse with qc_type: doorstep) |
| serial_no | character | serial_no of the item to be picked (only for shadowfax reverse with qc_type: doorstep) |
| size | character | size of the item to be picked (only for shadowfax reverse with qc_type: doorstep) |
| qc_rules | json array | questions to be asked by pickup boy (only for shadowfax reverse with qc_type: doorstep) |
If you want to pass above parameters as QC for other reverse logistics partners, please contact support@clickpost.in for integrations request.
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,
"from_wh": "From Warehouse",
"to_wh": "To Warehouse",
"channel_name": "Channel Name: In case you have different channels to receive orders",
"order_date": "YYYY-MM-DD",
"order_id": "order ID of the shipment",
"enable_whatsapp": false # Useful for whatsapp communication
}
}
Response
{
"meta": {
"message": "Order Placed Successfully",
"status": 200,
"success": true
},
"result": {
"sort_code": "DEL/SET",
"security_key": "560fee51-1af3-4d1d-a6e8-0149b0868d38",
"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",
"drop_email": "support@clickpost.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/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": "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",
"from_wh": "From Warehouse",
"to_wh": "To Warehouse",
"channel_name": "Channel Name: In case you have different channels to receive orders",
"order_id": "Order ID of the order"
}
}
Response
{
"meta": {
"message": "Order Placed Successfully",
"status": 200,
"success": true
},
"result": {
"security_key": "ee30803e-3fd9-460d-8cfa",
"sort_code": "ABC/XYZ",
"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
- security_key: All orders are allocated a security key, please store this security key in your system (36 chars)
- sort_code: for certain logistics partners, a sort_code is passed in API response that you can consume if you generate the shipping label at your end. For courier partners where this is not needed, it will have null value (13 chars) 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 API [MENA, EU, US, SEA]
URL to hit:
https://www.clickpost.in/api/v4/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": {
"city": "JK0701",
"name": "www.stylishop.com",
"time": "2020-02-01T10:53:33",
"email": "hello.ksa@stylishop.com",
"phone": "8001111090",
"state": "Al-Riyadh",
"address": "KRAMAT ASEM RAYA N0. 6, UTAN KAYU SELATAN, JAKARTA TIMUR 13120",
"landmark": null,
"phone_code": "+966",
"postal_code": "JK0701",
"country_code": "SA",
"district": "XYZ",
"lat": 10.01,
"long": 10.2
},
"drop_info": {
"city": "JK0703",
"name": "amal .",
"email": "a_maal11@hotmail.com",
"phone": "558022554",
"state": "Al-Riyadh",
"address": "JALAN PANJANG NO. 08, JAKARTA BARAT",
"landmark": null,
"phone_code": "+966",
"postal_code": "JK0703",
"country_code": "AE",
"district": "XYZ",
"lat": 10.01,
"long": 10.2
},
"return_info": {
"city": "Riyadh",
"name": "www.stylishop.com",
"email": "hello.ksa@stylishop.com",
"phone": "8001111090",
"state": "Al-Riyadh",
"address": "Retail Cart Trading Co., Makhzan2 New Warehouse, Al Bariah",
"landmark": null,
"phone_code": "+966",
"postal_code": "New Industrial Area",
"country_code": "SA",
"district": "XYZ",
"lat": 10.01,
"long": 10.2
},
"shipment_details": {
"items": [{
"sku": "3007940106",
"price": 35.00,
"quantity": 1,
"description": "Sample"
}, {
"sku": "3007930106",
"price": 35.00,
"quantity": 1,
"description": "Sample"
}],
"height": 10,
"length": 10,
"weight": 10,
"breadth": 10,
"cod_value": 0,
"order_type": "PREPAID",
"invoice_date": "2020-01-30",
"currency_code": "SAR",
"delivery_type": "FORWARD",
"invoice_value": 375,
"invoice_number": "3000020284",
"reference_number": "test3000019526",
"courier_partner": 2
},
"tax_info": null,
"additional": {
"rvp_reason": "Customer wants to return the product",
"async": false,
"label": true,
"order_date": "2020-01-30T20:14:34",
"vendor_code": "ADDR12182_1463",
"account_code": "SMSA Domestic",
"order_id": "Order Number of the Shipment",
"invoice_base_64": "base_64_string_of_invoice",
"duty_fee_paid_by":"S"
}
}
Response
{
"meta": {
"success": true,
"message": "Order Placed Successfully",
"status": 200
},
"result": {
"label": null,
"reference_number": "test13000019524",
"security_key": "b43c6e93-e555-44c5-ab76-f57090f78a40",
"waybill": "test13000019524",
"sort_code": null
}
}
The create order v4 API allows uploading the package details (manifest information) into the courier partner’s system and returns a waybill and 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.
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/v4/create-order/ where output format is json.
Listed below are the parameters:
URL parameters:
| Parameter | Type | Description |
|---|---|---|
| Username | character | User name provided to you by Clickpost team |
| key | character | API key provided to you by Clickpost team |
Fields Explanation [Payload]
pickup_info: [pickup location information]
| Parameter | Type | Description |
|---|---|---|
| name | character (100 characters) | name of person at pickup location which shall be contacted by courier partner |
| character (100 characters) | email of the person at pickup location | |
| phone_code | character | ISO phone code of the country where the pickup is to be done. Country and their phone codes: https://www.clickpost.in/api/v1/countries/ |
| phone | character (11 characters) | phone number of the person at pickup location |
| address | character (500 character) | address of pickup location |
| postal_code | character (50 character) | postal code of the pickup location. For MENA region, this field represents area code |
| city | character (200 character) | city of the pickup location |
| district | character (200 character) | district of the pickup location [Required for South East Asian countries] |
| state | character (200 character) | state of the pickup location |
| country_code | character | ISO country code of the country where pickup is to be done. Country code list: https://www.clickpost.in/api/v1/countries/ |
| lat | float | latitute of the pickup location |
| long | float | longitud of the pickup location |
drop_info (mandatory): [destination location information]
| Parameter | Type | Description |
|---|---|---|
| name | character (100 characters) | name of person at destination location who will be contacted by courier partner |
| character (100 characters) | email of the person at destination location | |
| phone_code | character | ISO phone code of the country where the delivery is to be done. Country and their phone codes: https://www.clickpost.in/api/v1/countries/ |
| phone | character (11 characters) | phone number of the person at destination location |
| address | character (500 character) | address of destination location |
| postal_code | character (50 character) | postal code of the destination location. For MENA region, this field represents area code |
| city | character (200 character) | city of the destination location |
| district | character (200 character) | district of the destination location [Required for South East Asian countries] |
| state | character (200 character) | state of the destination location |
| country_code | character | ISO country code of the country where destination is to be done. Country code list: https://www.clickpost.in/api/v1/countries/ |
| lat | float | latitute of the destination location |
| long | float | longitud of the destination location |
shipment_info: [shipment information]
| Parameter | Type | Description |
|---|---|---|
| order_type | string | type of shipment based on payment mode [Possible values: “COD”, “PREPAID”] |
| invoice_value | float | declared value of the shipment |
| cod_amount | float | cash on delivery amount, that courier has to collect while delivering the shipment |
| currency_code | string (3 characters) | ISO currency code of currency selected by customer for placing the order: Currency codes in Clickpost https://www.clickpost.in/api/v1/countries/ [https://en.wikipedia.org/wiki/ISO_4217] |
| reference_number | string (50 characters) | unique shipment ID for the shipment. (You can perform search on this parameter on Clickpost dashboard) |
| order_id | string (50 characters) | Order ID of the shipment |
| length | int | length in cms |
| height | int | height in cms |
| breadth | int | breadth in cms |
| weight | int | weight in grams |
Clickpost also accepts item (SKU: Stock Keeping Unit) level information with the shipment information, which enables you to use Clickpost’s returns platform. Please pass following attributes of item [SKU]:
| Parameter | Type | Description |
|---|---|---|
| sku | string (50 character) | SKU (Stock Keeping Unit) ID of the item |
| description | string (500 characters) | SKU description |
| quantity | int | quantity of SKU ordered by customer |
| price | float | price of 1 unit |
| images | string (1000 character) | image URL of the SKU |
| return_days | int | eligible days for return from the date, shipment was delivered to customer |
additional (optional): extra information about shipment used to power tracking page:
| Parameter | Type | Description |
|---|---|---|
| order_date | character | timestamp when the order was placed in yyyy-mm-dd format |
| ship_date | character | timestamp when order was ready to ship in yyyy-mm-dd format |
| min_edd | integer | minimum days commited to the customer for 1st delivery attempt |
| max_edd | integer | maximum days commited to the customer for 1st delivery attempt |
| enable_whatsapp | boolean | if you have whatsapp for business account, you can pass opt-in information here so Clickpost starts sending out communications to customers |
| order_id | character [50 characters] | order ID of the shipment |
| invoice_base_64 | character | base 64 string of invoice. Required by DHL for PLT (Paper Less Trade) process |
| rvp_reason | character | mandatory for reverse pickups [pickups from customer location]. Not required for forward, warehouse to customer |
| duty_fee_paid_by | character | defines who will be paying the duty charges for the shipment. Possible values: “S”: Shipper, “R”: Recipient [only applicable for UPS / DHL] |
Fetch AWB Number / Reference number for already manifested order
URL (To fetch awb / courier_partner for a reference_number):
https://www.clickpost.in/api/v3/create-order?key=<api-key>&reference_number=<reference_number>
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Response
{
"meta": {
"message": "Success",
"status": 200,
"success": true
},
"result": {
"security_key": "560fee51-1af3-4d1d-a6e8-0149b0868d38",
"courier_partner": 1,
"reference_number": "100035710-1-2-3",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/FEDEX/2019-03-31/8505644567.pdf",
"waybill": "8505644567"
}
}
URL (To check reference_number for an awb):
https://www.clickpost.in/api/v3/create-order?key=<api-key>&cp_id=<courier_partner_id>&awb=<waybill>
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Response
{
"meta": {
"message": "Success",
"status": 200,
"success": true
},
"result": {
"security_key": "560fee51-1af3-4d1d-a6e8-0149b0868d45",
"courier_partner": 1,
"reference_number": "100035710-1-2-3",
"label": "https://pyck-res-bucket.s3.amazonaws.com:443/FEDEX/2019-03-31/8505644567.pdf",
"waybill": "8505644567",
"sort_code": null
}
}
The API is a HTTP GET request to: https://www.clickpost.in/api/v3/create-order/ where output format is json.
The create-order GET API helps customers to fetch awb and shipping label for already manifested order before requesting for the AWB again for same shipment.
key is compulsory to pass for authentication. You must pass either reference_number or (cp_id and awb) in the API to get the result.
Listed below are the parameters:
URL parameters:
| Parameter | Type | Description |
|---|---|---|
| key | character | API key provided to you (mandatory) |
| reference_number | character | reference_number passed in the POST payload during manifestation (optional) |
| cp_id | integer | courier partner ID of Clickpost (optional) [list at http://track.clickpost.in/courier_partner] |
| awb | character | waybill number of the shipment (optional) |
Fetch shipping label
URL:
https://www.clickpost.in/api/v1/fetch/shippinglabel/?&key=<api-key>&waybill=<waybill>&cp_id=<cp_id>®enerate=false
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you)
Response
{
"result": {
"shipping_label": "https://pyck-res-bucket.s3.amazonaws.com:443/DELHIVERY/2019-03-01/258731.pdf"
},
"meta": {
"message": "SUCCESS",
"status": 200,
"success": true
}
}
Use this API to fetch shipping label for already manifested order. Its a GET API.
Listed below are the parameters:
URL parameters:
| Parameter | Type | Description |
|---|---|---|
| key | character | API key provided to you (mandatory) |
| cp_id | integer | courier partner ID of Clickpost (optional) [list at http://track.clickpost.in/courier_partner] |
| waybill | character | waybill number of the shipment (optional) |
Processing Async API requests
In case you have account with courier partner which does not support sync API, please follow the steps present here to process the request:
When you hit the request for the 1st time, Clickpost will queue the request and share the response with “meta” –> “status” = 202
Response [Async order creation request accepted]
{
"meta": {
"success": true,
"message": "Order Placed Successfully",
"status": 202
},
"order_id": 8488542,
"result": {
"reference_number": "TEST-ALPHA-132135",
"waybill": null,
"label": null,
"sort_code": null
}
}
Generally it takes 30 sec for the courier to process the request in async manner. Since Clickpost APIs are idempotent, you can continue to make the order creation request with same parameters, Clickpost will check the reference number and will return “meta” –> “status” 102 if the request is still under process:
Response [Async order creation request in process]
{
"order_id": 8488863,
"result": {
"waybill": null,
"sort_code": null,
"security_key": null,
"label": null,
"reference_number": "TEST-ALPHA-132135"
},
"meta": {
"message": "We are processing your order",
"success": false,
"status": 102
}
}
Once the request is processed and you make the polling call with same reference number on the same API, you will get success [status code 200 or 323] or failure depending on response from courier partner
Response [Async order creation Success]
{
"meta": {
"status": 323,
"message": "You have already placed this order",
"success": false
},
"result": {
"waybill": "1993933981231",
"sort_code": null,
"reference_number": "AR9-19-2697",
"label": "https://test-bucket.s3.amazonaws.com:443/test/2019-09-23/19939339821.pdf",
"security_key": "f60207d9-8bd9-441c-80e9-0c3781721fed"
},
"tracking_id": 52158761,
"order_id": 7127897
}
Response [Async order creation failure]
{
"order_id": 8488743,
"meta": {
"message": "{'status': {'reason': 'ConfigurationError<FAAS: warehouses<GURGOANTHEA> has not been configured>', 'job_id': 'b3f5be04-f916-4bef-b0d4-3d8753e8332f', 'success': False, 'value': 'ConfigurationError', 'type': 'Complete'}}",
"success": false,
"status": 319
},
"reference_number": "TEST-ALPHA-132135"
}
Track Order
Register a shipment for tracking: [IN]
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": "Test Customer",
"phone": "8080808080",
"email": "test@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": "110001",
"pickup_pincode": "110001",
"delivery_type": "FORWARD",
"cod_amount": 1000.10,
"drop_address": "Roots hacker Home, R 28, Second Floor, Nehru Enclace, Opposite Nehru Place, New Delhi 110001",
"additional": {
"items": [
{
"sku": "XYZ1",
"description": "item1",
"quantity": 1,
"price": 200,
"images": "<Image URL>",
"return_days": 2,
"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",
"min_edd": 2,
"max_edd": 4,
"enable_whatsapp": false,
"order_id": "ORDER-12"
}
}
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
}
}
Note: All orders are passed a security_key in response. Please store this security key to be used in Customer engagement platform.
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 sku, description, quantity, image, price and return_days for return management solution (easier for end customer to select which product to return) |
| additional –> items –> return_days | integer | number of days allowed for a product to be accepted as 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 |
| min_edd | integer | minimum days commited to the customer for 1st delivery attempt |
| max_edd | integer | maximum days commited to the customer for 1st delivery attempt |
| enable_whatsapp | boolean | if you have whatsapp for business account, you can pass opt-in information here so Clickpost starts sending out communications to customers |
| order_id | string (50 characters) | Order ID of the shipment |
API response: “meta” –> “status”: 200 and 303 represents success response
Register a shipment for tracking: [MENA, SEA, EU, US]
POST request URL:
https://www.clickpost.in/api/v3/tracking/awb-register/?key=<clickpost_api_key>
Headers: {'Content-type': 'application/json'}
Sample Payload
{
"waybill": "ABCDRESDEFGHIJKL",
"courier_partner": 1,
"account_code": "Fedex Domestic",
"shipment_info": {
"order_type": "COD",
"invoice_value": "12345",
"cod_amount": "1000",
"currency_code": "SAR",
"reference_number": "123XYZ",
"order_id": "order_id of the shipment",
"length": 10,
"height": 10,
"weight": 10,
"breadth": 10,
"items": [
{
"sku": "XYZ1",
"description": "item1",
"quantity": 1,
"price": 200,
"images": "<Image URL>",
"return_days": 2,
"length": 10,
"height": 10,
"breadth": 10,
"weight": 100
}
]
},
"pickup_info": {
"name": "Rashid Alma",
"email": "warehouse_1@hotmail.com",
"phone_code": "966",
"phone": "8001111090",
"address": "KRAMAT ASEM RAYA N0. 6, UTAN KAYU SELATAN, JAKARTA TIMUR 13120",
"postal_code": "JK0701",
"city": "Riyadh",
"district": "XYZ",
"state": "Al-Riyadh",
"country_code": "SA",
"lat": 10.01,
"long": 10.2
},
"drop_info": {
"name": "Amal Hisham",
"email": "a_maal11@hotmail.com",
"phone_code": "966",
"phone": "558022554",
"address": "JALAN PANJANG NO. 08, JAKARTA BARAT",
"postal_code": "JK0703",
"city": "JK0703",
"district": "XYZ",
"state": "Al-Riyadh",
"country_code": "AE",
"lat": 10.01,
"long": 10.01
},
"additional": {
"enable_whatsapp": false,
"language_code": "EN",
"order_date": "2017-02-14",
"ship_date": "2017-02-14",
"min_edd": 2,
"max_edd": 4
}
}
Response
{
"meta": {
"message": "SUCCESS",
"status": 200,
"success": true
},
"result": {
"security_key": "530470b0-8ebd-40c3-9c9e-6ca6bf1d29b8"
}
}
Note: All orders are passed a security_key in response. Please store this security key.
API response: “meta” –> “status”: 200 and 303 represents success response. All the other status codes represent a failure. Our API will always return HTTP status code 200.
Fields Explanation
Compulsory:
| Parameter | Type | Description |
|---|---|---|
| waybill (required) | character (100 chars) | this is/are comma separated waybill numbers for which the status is required |
| courier_partner (required) | integer | courier_partner ID of the courier on which you want to track the AWB. List of courier partners: http://track.clickpost.in/courier_partner |
| account_code (required) | character (100 chars) | account code in case you have multiple accounts for same courier partner |
Optional:
pickup_info (optional): [pickup location information: all the fields are optional]
| Parameter | Type | Description |
|---|---|---|
| name | character (100 characters) | name of person at pickup location which shall be contacted by courier partner |
| character (100 characters) | email of the person at pickup location | |
| phone_code | character | ISO phone code of the country where the pickup is to be done. Country and their phone codes: https://www.clickpost.in/api/v1/countries/ |
| phone | character (11 characters) | phone number of the person at pickup location |
| address | character (500 character) | address of pickup location |
| postal_code | character (50 character) | postal code of the pickup location. For MENA region, this field represents area code |
| city | character (200 character) | city of the pickup location |
| district | character (200 character) | district of the pickup location [Required for South East Asian countries] |
| state | character (200 character) | state of the pickup location |
| country_code | character | ISO country code of the country where pickup is to be done. Country code list: https://www.clickpost.in/api/v1/countries/ |
| lat | float | latitute of the pickup location |
| long | float | longitud of the pickup location |
drop_info (optional): [destination location information: all the fields are optional]
| Parameter | Type | Description |
|---|---|---|
| name | character (100 characters) | name of person at destination location who will be contacted by courier partner |
| character (100 characters) | email of the person at destination location | |
| phone_code | character | ISO phone code of the country where the delivery is to be done. Country and their phone codes: https://www.clickpost.in/api/v1/countries/ |
| phone | character (11 characters) | phone number of the person at destination location |
| address | character (500 character) | address of destination location |
| postal_code | character (50 character) | postal code of the destination location. For MENA region, this field represents area code |
| city | character (200 character) | city of the destination location |
| district | character (200 character) | district of the destination location [Required for South East Asian countries] |
| state | character (200 character) | state of the destination location |
| country_code | character | ISO country code of the country where destination is to be done. Country code list: https://www.clickpost.in/api/v1/countries/ |
| lat | float | latitute of the destination location |
| long | float | longitud of the destination location |
shipment_info (optional): shipment information for rich analytics on your data:
| Parameter | Type | Description |
|---|---|---|
| order_type | string | type of shipment based on payment mode [Possible values: “COD”, “PREPAID”] |
| invoice_value | float | declared value of the shipment |
| cod_amount | float | cash on delivery amount, that courier has to collect while delivering the shipment |
| currency_code | string (3 characters) | ISO currency code of currency selected by customer for placing the order: Currency codes in Clickpost https://www.clickpost.in/api/v1/countries/ [https://en.wikipedia.org/wiki/ISO_4217] |
| reference_number | string (50 characters) | unique shipment ID for the shipment. (You can perform search on this parameter on Clickpost dashboard) |
| order_id | string (50 characters) | Order ID of the shipment |
| length | int | length in cms |
| height | int | height in cms |
| breadth | int | breadth in cms |
| weight | int | weight in grams |
Clickpost also accepts item (SKU: Stock Keeping Unit) level information with the shipment information, which enables you to use Clickpost’s returns platform. Please pass following attributes of item [SKU]:
| Parameter | Type | Description |
|---|---|---|
| sku | string (50 character) | SKU (Stock Keeping Unit) ID of the item |
| description | string (500 characters) | SKU description |
| quantity | int | quantity of SKU ordered by customer |
| price | float | price of 1 unit |
| images | string (1000 character) | image URL of the SKU |
| return_days | int | eligible days for return from the date, shipment was delivered to customer |
additional (optional): extra information about shipment used to power tracking page:
| Parameter | Type | Description |
|---|---|---|
| order_date | character | timestamp when the order was placed in yyyy-mm-dd format |
| ship_date | character | timestamp when order was ready to ship in yyyy-mm-dd format |
| min_edd | integer | minimum days commited to the customer for 1st delivery attempt |
| max_edd | integer | maximum days commited to the customer for 1st delivery attempt |
| enable_whatsapp | boolean | if you have whatsapp for business account, you can pass opt-in information here so Clickpost starts sending out communications to customers |
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 [List of courier partners is present at: |
http://track.clickpost.in/courier_partner]
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
Fetch updated-orders list
URL
https://api.clickpost.in/api/v1/updated-order?username=<clickpost-username>&key=<clickpost-api-key>&start_date=1531980785&end_date=1531984399
Headers: {'Content-type': 'application/json'}
Response
{
"result": [
{
"created_at": "2019-04-15T14:52:45.304018Z",
"timestamp": "2019-04-15 20:22:43",
"clickpost_status_description": "OrderPlaced",
"clickpost_status_code": 1,
"courier_partner": 9,
"waybill": "SF41917204SCR",
"updated_at": "2019-04-15T15:00:04.672388Z",
"account_code": "test",
"reference_number": "CP-35416108",
"status": "001",
"location": "Mumbai Hub",
"remark": "Order Manifested in Courier System"
},
{
"created_at": "2019-04-15T14:47:26.614788Z",
"timestamp": "2019-04-15 20:17:25",
"clickpost_status_description": "OrderPlaced",
"clickpost_status_code": 1,
"courier_partner": 9,
"waybill": "SF41917199SCR",
"updated_at": "2019-04-15T15:00:07.132808Z",
"account_code": "test",
"reference_number": "CP-35416108",
"status": "Data Received Successfully",
"location": "Bangalore Hub",
"remark": "Order Manifested in Courier System"
},
{
"created_at": "2019-04-15T13:58:34.822899Z",
"timestamp": "2019-04-15 19:28:33",
"clickpost_status_description": "OrderPlaced",
"clickpost_status_code": 1,
"courier_partner": 9,
"waybill": "SF41917168SCR",
"updated_at": "2019-04-15T15:00:42.625536Z",
"account_code": "test",
"reference_number": "CP-35416108",
"status": "001",
"location": "New Delhi",
"remark": "Order Manifested in Courier System"
}
],
"meta": {
"message": "SUCCESS",
"status": 200,
"success": true
}
}
The updated-order API retrieves the shipments which are updated between specified start and end time.
The API is a HTTP GET request to:
https://api.clickpost.in/api/v1/updated-order
[earlier it was https://www.clickpost.in/api/v1/updated-order, which will deprecate by Nov 2020]
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 |
| start_date (required) | integer | start time for the query to run. To be passed in epoch time |
| end_date (required) | integer | end time for the query to run. To be passed in epoch time |
Note: The difference between start_date and end_date cannot be more than 30 minutes. If you plan to use polling, Its highly recommended to 1st run updated-order API, get list of updated shipments and then request the status details if required for those shipments using polling.
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://api.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": [],
"courier_partner_edd": "2020-03-20",
"rto_intransit_timestamp": "2020-05-30 20:59:00",
"ndr": {
"ndr_bucket_code": 1,
"ndr_description": "Customer unavailable"
},
"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": "FailedDelivery",
"clickpost_status_code": 9,
"clickpost_status_bucket": 5,
"status": "Delivery attempted: customer not available",
"location": "",
"remark": "Delivery attempted: customer not available",
"tracking_id": 12087879,
"timestamp": "2018-07-07 10:53:01",
"checkpoint_id": 163496679
},
{
"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
}
}
}
The track-order API retrieves the historic statuses and the current status of the package.
The API is a HTTP GET request to:
https://api.clickpost.in/api/v2/track-order/
[earlier it was https://www.clickpost.in/api/v2/track-order/, which will deprecate by Nov 2020]
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 |
Note: You can query upto 15 waybills [AWBs] status in 1 API request
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:
- “additional”: gives additional information about the shipment:
- courier_partner_edd: Expected delivery date as given by courier partner over APIs
- rto_intransit_timestamp: timestamp of 1st RTO Intransit scan received by Clickpost systems from courier partner
- “latest_status”: 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
Clickpost exposes webhooks for status updates in 2 ways:
For all events/status: This will trigger status updates for all the scans done by courier partner for the shipment. You can opt in for these webhooks using “Webhooks: All Status” on the dashboard. From tech perspective, apply check on clickpost_status_code in latest_status to update the status in your system.
For selected events/status: This will trigger status updates only for selected checkpoints opted by you on the Clickpost dashboard. You can opt in for these webhooks using “Webhooks: Selected Status” on the dashboard. From tech perspective, apply check on notification_event_id in the webhook object to update the status in your system. The checkpoints available for Selected webhooks are as mentioned on the dashboard.
Webhook Payload Header
{
"Content-Type": "application/json",
"webhook_key": "webhook_key_given_during_webhooks_register"
}
Webhook Payload
{
"additional": {
"latest_status": {
"remark": "Shipment is Out for Delivery",
"clickpost_status_code": 6,
"reference_number": "WERA-9616974",
"timestamp": "2019-05-06T10:04:20Z",
"clickpost_status_bucket_description": "Out for delivery",
"location": "DEL_GeetaColony",
"clickpost_status_description": "OutForDelivery",
"clickpost_status_bucket": 4,
"status": "OFD"
},
"is_rvp": false,
"courier_partner_edd": "2020-03-25"
},
"remark": "Shipment is Out for Delivery",
"clickpost_status_description": "OutForDelivery",
"timestamp": "2019-05-06T10:04:20Z",
"location": "DEL_GeetaColony",
"status": "OFD",
"cp_id": 9,
"clickpost_status_code": 6,
"waybill": "SF49245NER"
}
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:36Z",
"clickpost_status_code": 9,
"clickpost_status_description": "FailedDelivery",
"cp_id": 1,
"additional": {
"latest_status": {
"reference_number": "WERA-9616974",
"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:36Z",
"remark": "Failed Delivery"
},
"ndr_status_code": 1,
"ndr_status_description": "Customer Unavailable",
"is_rvp": false,
"courier_partner_edd": null
}
}
Activating Webhooks:
- Visit Clickpost dashboard: Settings Tab on the left and Click notification section
- Select webhooks and activate Selected Events webhooks configuration or All Events Webhooks configuration as per your need.
- Selected webhooks configuration: trigger webhooks only when shipment reaches certain checkpoints in its journey.
- All webhooks configuration: trigger webhooks for all shipment statuses as they come.
We generally recommend customers to use selected webhooks configuration as all webhooks will trigger too many status messages on your system.
Note:
If you wish to configure the basic token auth also along with the webhooks the headers will change as follows:
{
"Content-Type": "application/json",
"Authorization": "<value entered on the dashboard for the token under basic token auth section>"
}
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 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
- While consuming the webhooks do not apply strict JSON check in the code as you might have new keys in the payload as we enhance the services.
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 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. [Visit “Tracking Status Codes” section]
- clickpost_status_description: description of clickpost_status_code [Visit “Tracking Status Codes” section]
- courier_partner_edd: Expected delivery date as given by courier partner over APIs
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” |
| 12 | “Customer wants open delivery” |
| 13 | “Shipment Misrouted by logistics partner” |
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:
| Value | Description |
|---|---|
| 1 | Out For Pickup |
| 2 | Shipped |
| 3 | Out For Delivery |
| 4 | Failed Delivery |
| 5 | Delivered |
| 6 | RTO |
| 10 | Order Cancelled |
| 12 | RTO-Delivered |
| 14 | Exchange Pickup |
| 15 | Exchange Delivered |
| 16 | Pickup Cancelled |
| 17 | Shipment Stuck |
| 18 | SLA breached |
| 19 | Lost |
| 20 | Damaged |
Following notification_event_id are useful for customers using Clickpost’s managed returns service which accepts return requests from end user:
| Value | Description |
|---|---|
| 9 | AWB Generated: As soon as an AWB is generated in Clickpost for a return request |
| 11 | Return Request placed: As soon as a return request is placed by the end user using Clickpost’s return UI |
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” |
| 12 | “Customer wants open delivery” |
| 13 | “Shipment Misrouted by logistics partner” |
Please see the sample payload on the right.
Selected event subscribed webhook: Failed delivery Payload
{
"waybill": "2614010163240",
"remark": "Customer escalation received",
"clickpost_status_code": 9,
"status": "Pending",
"clickpost_status_description": "FailedDelivery",
"location": "Lucknow_Aliganj (Uttar Pradesh)",
"timestamp": "2019-05-01T00:55:06Z",
"cp_id": 4,
"additional": {
"ndr_status_code": 1,
"ndr_status_description": "Customer unavailable",
"notification_event_id": 4,
"is_rvp": false,
"courier_partner_edd": "2020-03-25",
"latest_status": {
"reference_number": "WERA-NMS1908MSO2",
"remark": "Customer escalation received",
"clickpost_status_code": 9,
"status": "Pending",
"location": "Lucknow_Aliganj (Uttar Pradesh)",
"clickpost_status_bucket_description": "Failed delivery",
"clickpost_status_description": "FailedDelivery",
"timestamp": "2019-05-01T00:55:06Z",
"clickpost_status_bucket": 5
}
}
}
Selected event subscribed webhook: Delivered Payload
{
"status": "Delivered",
"clickpost_status_code": 8,
"waybill": "12527345",
"clickpost_status_description": "Delivered",
"location": "Nayagarh_Durgprsd_D (Orissa)",
"cp_id": 4,
"remark": "Delivered to consignee",
"timestamp": "2019-05-06T15:01:00Z",
"additional": {
"notification_event_id": 5,
"is_rvp": false,
"courier_partner_edd": "2020-03-25",
"latest_status": {
"status": "Delivered",
"reference_number": "WERA-NMS1908MSO2",
"clickpost_status_bucket_description": "Delivered",
"clickpost_status_description": "Delivered",
"clickpost_status_code": 8,
"location": "Nayagarh_Durgprsd_D (Orissa)",
"clickpost_status_bucket": 6,
"remark": "Delivered to consignee",
"timestamp": "2019-05-06T15:01:00Z"
}
}
}
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:36Z",
"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:36Z",
"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.
Track Return Order
Return Order Placed Webhook
Webhook Payload Header
{
"Content-Type": "application/json",
"webhook_key": "webhook_key_given_during_webhooks_register"
}
Webhook Payload
{
"location": "",
"remark": "Return Order Placed",
"notification_event": 11,
"timestamp": "2019-04-29 07:47:07.161221",
"clickpost_status_code": 101,
"cp_id": -1,
"clickpost_status_bucket_description": "Return Order Placed",
"waybill": "",
"clickpost_status_bucket": 8,
"status": "Return Order Placed",
"clickpost_status_description": "Return Order Placed",
"additional": {
"latest_status": {
"clickpost_status_bucket_description": "Return Order Placed",
"clickpost_status_description": "Return Order Placed",
"clickpost_status_bucket": 8,
"remark": "Return Order Placed",
"status": "Return Order Placed",
"location": "",
"timestamp": "2019-04-29 07:47:07.161252",
"clickpost_status_code": 101
},
"is_rvp": true,
"notification_event_id": 11,
"forward_awb": "5522110373319",
"self_shipped": false,
"forward_reference_number": "1405277",
"item_info": [{
"sku": "120667",
"quantity": 1
}, {
"sku": "9649",
"quantity": 1
}, {
"sku": "46457",
"quantity": 1
}, {
"sku": "10924",
"quantity": 1
}],
}
}
This webhook is only useful for customers using Clickpost managed returns platform to accept customer returns on their website.
Activating Return order placed webhook:
- Visit Clickpost dashboard: Settings Tab on the right and Click notification section
- Select webhooks and activate Selected webhooks configuration –> “Return Order Placed”.
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
- forward_reference_number will have the corresponding reference number.
- waybill number will be blank as order is not yet created on courier partner (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.
- item_info: represents the item details for which return request is raised by the customer
Logic to be applied on webhook endpoint to detect returns webhook: In all reverse pickup order webhooks, is_rvp will be true. If its true, check the forward_awb or forward_reference_number in the payload, verify it with the same in your system and update the sku(s) present in item_info.
Cancel Shipment API
URL to hit:
https://www.clickpost.in/api/v1/cancel-order/?username=test&key=42d42a34-ae09-469312b20c-ae2624&waybill=782715732348&cp_id=8&account_code=cli12
Headers: {'Content-type': 'application/json'}
(Username/key needs to be replaced with the username/key provided to you) Response:
Example: GET 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
- account_code (optional): in case you have multiple courier accounts for a courier partner on Clickpost, please pass account_code in the cancellation API so that clickpost uses correct credentials to mark the shipment cancel
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
Serviceability V1 API
Gives list of only those courier partners where atleast one of the service [COD/PREPAID/EXCHANGE] is active
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"
},
"drop_pincode": "110020",
"pickup_pincode": "122002"
}]
Response
{
"result": [
{
"cp_id": 3,
"serviceable": {
"PREPAID": true,
"COD": false,
"EXCHANGE": false # EXCHANGE: true is returned only for service_type: RVP
},
"comitted_sla": null,
"account_code": "Sample_Ecom_1",
"shipping_charge": {
"PREPAID": null,
"COD": null
}
},
{
"cp_id": 3,
"serviceable": {
"PREPAID": false,
"COD": true
},
"comitted_sla": null,
"account_code": "Sample_Ecom_2",
"shipping_charge": {
"PREPAID": null,
"COD": null
}
}
],
"meta": {
"success": true,
"status": 200,
"message": "SUCCESS"
}
}
Serviceability api V1 checks if pickup and drop pincodes are serviceabile or not, shipping charges for the shipment [if you have opted to get shipping charges] and turn around time [if you have opted to get TAT] 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, 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:
Serviceability V2 API
URL to hit
https://www.clickpost.in/api/v2/serviceability_api/?username=test&key=a090-30ce18a2b96c
(username and key needs to be replaced with the key provided to you)
Example(POST Body)
[{
"drop_pincode": "110020",
"pickup_pincode": "122002"
}]
Response
{
"result": [
{
"service_type": "FORWARD",
"account_id": 737,
"shipping_charge": {},
"account_code": "Xpressbees Surface",
"comitted_sla": null,
"cp_id": 6,
"serviceable": {
"EXCHANGE": false,
"PICKUP": true,
"COD": true,
"PREPAID": true
}
},
{
"service_type": "FORWARD",
"account_id": 723,
"shipping_charge": {},
"account_code": "Delhivery Express",
"comitted_sla": null,
"cp_id": 4,
"serviceable": {
"EXCHANGE": false,
"PICKUP": true,
"COD": true,
"PREPAID": true
}
}
],
"meta": {
"status": 200,
"message": "SUCCESS",
"success": true
}
}
Serviceability API checks if pickup and drop pincodes are serviceable or not, shipping charges for the shipment and turn around time for the delivery.
It’s a POST request as follows
URL:
https://www.clickpost.in/api/v2/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 |
|---|---|---|
| service_type | character | Any one of FORWARD/RVP, 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
- PICKUP: If pickup pincode is serviceable
- EXCHANGE: If exchange is serviceable
- 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:
Bulk Serviceability API
URL to hit
https://www.clickpost.in/api/v1/bulk_serviceability_api/?username=test&key=a090-30ce18a2b96c743dhg-djhsu2&courier_partner_id=<cp_id>&account_code=<account_code>
(username and key needs to be replaced with the key provided to you)
Response
{
"result": {
"pickup_pincodes": {
"PREPAID": [
"690546"
]
},
"drop_pincodes": {
"PREPAID": [
"560067",
"560102"
],
"COD": [
"855114"
]
}
},
"meta": {
"success": true,
"status": 200,
"message": "Success"
}
}
Bulk Serviceability API takes courier_partner_id and account_code as input and returns all the pickup and drop pincodes along with order_types serviceable for that account present in Clickpost.
It’s a GET request
URL:
https://www.clickpost.in/api/v1/bulk_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 |
| courier_partner_id | integer | courier partner ID |
| account_code | character | account code as added in Clickpost dashboard |
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:
- pickup_pincodes: JSON object with value as:
- PREPAID: All pickup pincodes
- drop_pincodes: JSON object with 3 possible values:
- COD: All COD pincodes
- PREPAID: All PREPAID pincodes
- EXCHANGE: All EXCHANGE pincodes
- pickup_pincodes: JSON object with value as:
Expected Date of Delivery API
URL to hit
https://ds.clickpost.in/api/v2/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",
"account_code": "Bluedart"
}
}
]
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://ds.clickpost.in/api/v2/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 |
| end_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
Whatsapp opt-out/opt-in API
URL
https://www.clickpost.in/api/v1/enable_shipment_notification/?key=<enterprise_key>
Headers: {'Content-type': 'application/json'}
Request
{
"awb":"<awb_number>",
"whatsapp_disable":true
}
Response
{
"meta": {
"success": true,
"status": 200,
"message": "SUCCESS"
}
}
The whatsapp optin API allows you to inform Clickpost systems if whatsapp communication shall be enabled/disabled for a particular shipment.
The API is a HTTP POST request to:
https://www.clickpost.in/api/v1/enable_shipment_notification/
where output is json
Listed below are the URL parameters:
| Parameter | Type | Description |
|---|---|---|
| key (required) | character | your Clickpost API Key |
Payload
| Parameter | Type | Description |
|---|---|---|
| awb | character | shipment for which action is to be performed |
| whatsapp_enable | boolean | action to be done: true implies whatsapp communication shall be sent for the shipment, false implies whatsapp communication shall be disabled |
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
- status: 200, if the API data was fine
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_FAILED | 'Pickup Failed’ |
| 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’ |
| 30 | EXCHANGE_PICKUP | 'Exchange successful, Shipment delivered and picked up from the customer’ [Only for exchange service] |
| 31 | EXCHANGE_INTRANSIT | 'Exchanged shipment In Transit to warehouse’ [Only for exchange service] |
| 32 | EXCHANGE_DELIVERED | 'When an exchange shipment is delivered back’ [Only for exchange service] |
| 101 | RETURN ORDER PLACED | 'Order Placed in Clickpost for reverse pickup by Customer’ # Only useful for customers using Returns Management Platform of 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 |
| 202 | Cancellation request received, failed over API, will be mailed to the couriers [Applicable for couriers where cancel request is sent via mail post API failure] |