Register shipment for tracking: V2

Using this API enterprises can register an AWB for tracking updates with Clickpost. It takes the AWB number, carrier partner ID, shipment information, pick-up and drop information and additional details as input and returns the Clickpost tracking ID in response.

Overview

Register an AWB for tracking updates with Clickpost, given the AWB number, carrier partner ID, shipment information, pick-up and drop information and additional details as input. Applicable for Indian geographies.

Usecase

This is a standard API that supports MPS and SPS orders

URL

POST https://www.clickpost.in/api/v2/tracking/awb-register/

Body Payload

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

Field NameData TypeFieldDescriptionMax LengthExample
waybillStringMandatoryAWB to be registered100"TESTAWB00001"
cp_idIntegerMandatoryEach carrier partner has a unique identifier (Integer value) in the Clickpost system, which will be used to identify the courier partner and track the shipment. List: https://carriers.clickpost.ai/215
keyStringMandatoryUnique license key for the enterprise user provided by Clickpost100"34be9be5-3de8-4223-ad14-d7391159b80e"
account_codeStringMandatoryCourier partner account name configured on the Clickpost dashboard100"test_account"
consumer_detailsObjectOptionalDetails of the consumer
shipment_infoObjectOptionalDetails of the shipment to be registered
pickup_infoObjectOptionalDetails of the pickup location
drop_infoObjectOptionalDetails of the drop location
additionalObjectOptionalAdditional optional fields

Consumer Details (consumer_details)

Field NameData TypeFieldDescriptionMax LengthExample
nameStringMandatoryName of the consumer250"Test Customer"
phoneStringMandatoryPhone number of the consumer80"8080808080"
emailStringOptionalEmail of the consumer150"[email protected]"

Additional Fields (additional)

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

Field NameData TypeFieldDescriptionMax LengthExample
order_dateDateOptionalDate of placing the order. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z50"2022-10-01"
ship_dateDateOptionalDate of shipping the order. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z50"2022-10-01"
language_codeStringOptionalISO Alpha-3 Language code for the shipment3"eng"
min_eddIntegerOptionalMinimum committed estimated delivery duration (in days) of the shipment5
max_eddIntegerOptionalMaximum committed estimated delivery duration (in days) of the shipment5
channel_nameStringOptionalThe channel through which the order was placed. Example: Unicommerce, EasyEcom, Shopify, Retail StoreUnicommerce
zoneStringOptional

If you wish to club multiple pickup-drop pin-codes together for easier recommendation allocation rule or for better visibility on internal business metrics based on a collection of pin-codes, this field is handy.

The zone wise analytics* will be visible under Home > Analytics > Zone Analysis

estimated_delivery_dateDateOptionalThe date of estimated delivery has been shared with the customer. This field can be used to measure carrier performance by comparing it with the actual date of delivery in the Clickpost reports. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z"2025-06-14"
allocation_dateDateOptionalAllocation date. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z"2017-02-14T18:00:00+05:30"
channel_order_idStringOptionalChannel order ID"channel_order_id"
order_idStringOptionalOrder ID"ORDER-12"
from_whStringOptionalsource warehouse"SOURCE WAREHOUSE"
to_whStringOptionaldestination warehouse"DESTINATION WAREHOUSE"
user_defined_field_arrayList[Object]OptionalCustom user-defined fields. Supported names: udf_1 to udf_10. Each object contains name, type, and value[{"name":"udf_1","type":"string","value":"high"}]
cp_specific_fieldsObjectOptionalCarrier-specific key-value fields{"vendor_code":"ABC"}

Shipment Info (shipment_info)

In the shipment_info field, the details regarding all items, and important order details like payment type, delivery type, package dimensions, etc. are added.

Field NameData TypeFieldDescriptionMax LengthExample
itemStringOptionalShort description of the item / package500"Shirt"
heightIntegerOptionalHeight of the overall package (in cms)25
breadthIntegerOptionalWidth of the overall package (in cms)45
lengthIntegerOptionalLength of the overall package (in cms)75
weightIntegerOptionalWeight of the package (in gms)500
reference_numberStringOptionalReference number of the order100"TestOrder00001"
cod_amountFloatOptionalCash to be given to the carrier. Must be non-zero for COD orders, and zero for PREPAID orders25.25
order_idStringOptionalIdentification string for the order100"TestOrderID00001"
order_typeStringOptionalType of payment of the shipment. Accepted values: "COD", "PREPAID", "EXCHANGE""COD"
delivery_typeStringOptionalType of delivery. Accepted values: "FORWARD", "RVP""FORWARD"
invoice_valueFloatOptionalValue of the shipment as mentioned in the invoice256.29
invoice_urlStringOptionalURL of the invoice
currency_codeStringOptionalCurrency code for monetary fields"INR"
shipping_chargesFloatOptionalShipping charges for the shipment50.0
sku_codeStringOptionalSKU code at shipment level500"SKU0001"
source_warehouseStringOptionalSource warehouse identifier200"WH-DEL"
pickup_pincodeStringOptionalPickup pincode100"110001"
drop_pincodeStringOptionalDrop pincode100"560001"
drop_addressStringOptionalDrop address500"123, ABC Street"
pickup_latFloatOptionalLatitude of the pickup location45.12211
pickup_longFloatOptionalLongitude of the pickup location88.12342
drop_latFloatOptionalLatitude of the drop location45.12211
drop_longFloatOptionalLongitude of the drop location88.12342
drop_start_timeDateOptionalDrop window start. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z"2025-06-14T10:00:00+05:30"
drop_end_timeDateOptionalDrop window end. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z"2025-06-14T18:00:00+05:30"
additionalObjectOptionalNested object containing item-level details via the items array

Item Level details (shipment_info.additional.items)

The details for each item to be delivered are passed in the items field inside shipment_info.additional.

Field NameData TypeFieldDescriptionMax LengthExample
skuStringOptionalStock-keeping unit of the item500"SKU0001"
descriptionStringOptionalBrief description of the item500"Brown Cotton Socks - 1 pair"
quantityIntegerOptionalNumber of units of the item5
weightIntegerOptionalWeight of each unit of the item (in gms)500
priceFloatOptionalPrice of each unit of the item64.99
catStringOptionalCategory of the item in questionFootwear
return_daysIntegerOptionalNumber of days within which the item can be returned5
product_urlStringOptionalURL for the product. If there are multiple URLs, they can be sent as a single string with comma-separated values1000"http://link1.to.product, http://link2.to.product"
imagesStringOptionalURL for the image(s) of the product. If there are multiple URLs, they can be sent as a single string with comma-separated values1000"http://link.to.product.image1, http://link.to.product.image2"
lengthIntegerOptionalLength of the item (in cms)10
breadthIntegerOptionalBreadth of the item (in cms)10
heightIntegerOptionalHeight of the item (in cms)10
brandStringOptionalBrand of the item100"Nike"
colorStringOptionalColor of the item"Brown"
discountFloatOptionalDiscount amount10.0
store_credits_usedFloatOptionalStore credits used for the item0

Pickup Info (pickup_info)

Field NameData TypeFieldDescriptionExample
nameStringOptionalPickup contact name"John Smith"
phoneStringOptionalPickup contact phone"9876543210"
phone_codeStringOptionalCountry dialing code"91"
emailStringOptionalPickup contact email"[email protected]"
addressStringOptionalPickup address"123, ABC Street"
cityStringOptionalPickup city"New Delhi"
stateStringOptionalPickup state"Delhi"
districtStringOptionalPickup district
pincodeStringOptionalPickup pincode"110001"
postal_codeStringOptionalPickup postal code"110001"
country_codeStringOptionalAlpha-2 ISO country code"IN"
latFloatOptionalLatitude of the pickup location28.6139
longFloatOptionalLongitude of the pickup location77.2090
pickup_organisationStringOptionalPickup organisation name
timeDateOptionalPickup time. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z"2025-06-14T10:00:00"

Drop Info (drop_info)

Field NameData TypeFieldDescriptionExample
nameStringOptionalDrop contact name"Test Customer"
phoneStringOptionalDrop contact phone"8080808080"
phone_codeStringOptionalCountry dialing code"91"
emailStringOptionalDrop contact email"[email protected]"
addressStringOptionalDrop address"123, MG Road"
cityStringOptionalDrop city"Bengaluru"
stateStringOptionalDrop state"Karnataka"
districtStringOptionalDrop district
landmarkStringOptionalLandmark near the drop location
pincodeStringOptionalDrop pincode"560001"
postal_codeStringOptionalDrop postal code"560001"
country_codeStringOptionalAlpha-2 ISO country code"IN"
latFloatOptionalLatitude of the drop location12.9716
longFloatOptionalLongitude of the drop location77.5946
drop_organisationStringOptionalDrop organisation name
drop_start_timeDateOptionalDrop window start. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z"2025-06-14T10:00:00+05:30"
drop_end_timeDateOptionalDrop window end. Accepted formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS%z, YYYY-MM-DD HH:MM:SS%z"2025-06-14T18:00:00+05:30"
user_categoryStringOptionalUser category
collection_point_idStringOptionalCollection point ID

Response

The sample response can have the following fields

Field NameData TypeDescription
metaObjectMetadata for the result, e.g. status code, error messages.
resultObjectActual result of the request
errorDetailList[String]Detailed validation or error messages, when applicable

Response Meta

Field NameData TypeDescription
statusIntegerStatus code of the response (including, but not limited to HTTP Status codes)
messageStringError message (if any errors) for the request.
successBooleanWhether the request is successful or not.

Response Result

Field NameData TypeDescription
tracking_idIntegerTracking ID of the newly registered waybill stored in our database.
security_keyStringUUID string for the security key of the order
shipment_infoObject or FalseAn object that contains only a single field: id that is the ID of the shipment. If shipment_info was not passed in the request body, it will be returned as Boolean False
consumer_detailsObject or FalseAn object that contains only a single field: id that is the ID of the consumer. If consumer_details was not passed in the request body, it will be returned as Boolean False

Sample Request

{
  "waybill": "ABCDRESDEFGHIJKL1257679",
  "cp_id": 1,
  "key": "42d42a34-ae09-4693-b20c-ae2624218a329",
  "account_code": "Fedex Domestic",
  "consumer_details": {
    "name": "Test Customer",
    "phone": "8080808080",
    "email": "[email protected]"
  },
  "shipment_info": {
    "item": "Shirt",
    "order_type": "COD",
    "invoice_value": 1000,
    "reference_number": "123XYZ",
    "length": 10,
    "height": 10,
    "weight": 10,
    "breadth": 10,
    "pickup_lat": 45.12211,
    "pickup_long": 88.12342,
    "drop_lat": 45.12211,
    "drop_long": 88.12342,
    "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,
          "length": 10,
          "height": 10,
          "breadth": 10,
          "weight": 100
        }
      ]
    }
  },
  "additional": {
    "order_date": "2017-02-14",
    "ship_date": "2017-02-14",
    "min_edd": 2,
    "max_edd": 4,
    "estimated_delivery_date": "2025-06-14",
    "order_id": "ORDER-12",
    "allocation_date": "2017-02-14T18:00:00+05:30",
    "channel_order_id": "channel_123",
    "from_wh": "SOURCE WAREHOUSE",
    "to_wh": "DESTINATION WAREHOUSE"
  }
}

Sample Response

Success

{
    "meta": {
        "status": 200,
        "message": "SUCCESS",
        "success": true
    },
    "result": {
        "consumer_details": {
            "id": 475565855
        },
        "shipment_info": {
            "id": 456652061
        },
        "tracking_id": 494235601,
        "security_key": "35aae392-5009-436a-b29b-7ddb2db518ab"
    },
    "errorDetail": null
}
{
    "meta": {
        "status": 303,
        "message": "Waybill already registered",
        "success": false
    },
    "result": null,
    "errorDetail": [
        "Waybill already registered"
    ]
}

Authentication Errors

{
    "meta": {
        "status": 301,
        "message": "Authentication Failed: Invalid API Key",
        "success": false
    }
}

Account Errors

{
    "meta": {
        "status": 353,
        "success": false,
        "message": "Clickpost Account: Inactive"
    },
    "result": null,
    "errorDetail": [
        {
            "message": "Clickpost Account: Inactive for courier partner 4 and account code shop3",
            "bucket": "ACCOUNT_INACTIVE",
            "recommendedActions": "The Clickpost account for this courier partner and account code is inactive. Activate it, then retry."
        }
    ]
}
{
    "meta": {
        "status": 351,
        "success": false,
        "message": "Clickpost Account: Does not exist"
    },
    "result": null,
    "errorDetail": [
        {
            "message": "Clickpost Account: Does not exist for courier partner 4 and account code shop213456781",
            "bucket": "ACCOUNT_NOT_FOUND",
            "recommendedActions": "No Clickpost account exists for this courier partner and account code. Create the courier account or correct the account code, then retry."
        }
    ]
}
{
    "meta": {
        "status": 302,
        "success": false,
        "message": "Invalid CP ID"
    },
    "result": null,
    "errorDetail": [
        {
            "message": "Invalid CP ID",
            "bucket": "INVALID_COURIER_PARTNER",
            "recommendedActions": "The courier partner id is invalid. Pass a supported courier partner and retry."
        }
    ]
}

Validation Errors

{
    "meta": {
        "status": 400,
        "message": "Error: Invalid API request data",
        "success": false
    },
    "result": null,
    "errorDetail": [
        "waybill is required and cannot be blank"
    ]
}
{
    "meta": {
        "status": 400,
        "message": "Error: Invalid API request data",
        "success": false
    },
    "result": null,
    "errorDetail": [
        "shipment_info.order_type must be COD, PREPAID or EXCHANGE"
    ]
}
{
    "meta": {
        "status": 328,
        "message": "Invalid Payload. Please pass a valid json",
        "success": false
    },
    "result": null,
    "errorDetail": [
        "Unexpected JSON token at offset 0"
    ]
}

Zone Wise Analytics


Did this page help you?