Create SPS Order: India
This API takes the shipment details, drop information, pickup information and creates an order with specified carrier partner. Applies for Single-Piece shipments within India only.
Overview
To create orders with domestic (Indian) carriers, Clickpost has provided the V3 Order Creation API that caters specifically to Indian customers and carriers. Enterprises can place both Single Piece and Multi-Piece Shipments with this API, to be delivered by their preferred carrier.
This specifically deals with Business-to-Consumer shipments.
Important Links
Usecase
Type of Shipment:
Forward Shipment
Forward shipments refer to the movement of goods from the point of origin (such as a warehouse or distribution centre) to the end customer or destination address.
Reverse Shipment
Reverse shipments involve the movement of goods from the delivery destination back to the point of origin or another specified location.
This is a standard API which applies to both B2C and B2B shipments.
Geography
This is a standard API which supports all shipments created and transported within India.
Processing Async Requests
In case you have account with carrier which does not support a synchronous API (one where the orders are created in real-time than in the background), please follow the steps present here to process the request:
- When you hit the request for the first time, Clickpost will queue the request and share the response with
meta –> status
= 202. For referring to the order, most carriers will return ajob_id
or some equivalent field in the response. - Generally it takes 30 sec for the carrier to process the request in async manner. Subsequently you can continue to make the order creation request with same parameters (this process is called polling) and Clickpost will check the reference number and will return
meta –> status
value as 102 if the request is still under process. - Once the request is processed and you make the polling call with the same reference number on the same API endpoint, you will either get success [status code 200 or 323] or failure depending on the response from the carrier.
It is also possible that the customer might want to place an async request in Clickpost's servers as well, regardless of whether the carrier supports an async API. In that case, set async
to True
in the additional
object in the payload, and Clickpost will process the request in the background. In this case also the customer can make polling calls to Clickpost's API with the same payload, and after a while the results of the order will be fetched once the order has been successfully placed.
Placing Reverse Shipment (RVP) Requests
The customer can also use this API to place Reverse Shipment (RVP) orders, orders that typically are picked up from the end-user's address and sent to the enterprise warehouse. The payload used for the request for placing an order is mostly the same as forward shipments, but 3 points need to considered in order to place a successful RVP order (All of these are mandatory, and Clickpost will throw errors if one of these is not fulfilled):
- The carrier partner to be used to place the RVP order must support RVP shipments. Ensure that the value passed in the
courier_partner
field is the partner ID for a carrier that supports RVP shipments. - Ensure that the
delivery_type
field in theshipment_details
object has the value"RVP"
. - Ensure that the
rvp_reason
field is added in theadditional
object.
Reverse Shipment with QC (Quality Check)
Reverse shipment with QC refers to the process of inspecting and verifying products at the moment of their return by the end customer, specifically during the collection phase by the carrier partner. This quality control check is conducted on returned items to ensure that they match the originally delivered products and meet the required quality standards.
More Details Here
Path
POST <https://www.clickpost.in/api/v3/create-order/?username=*****&key=*****
>
Query Parameters
Query Parameters to be passed directly in the URL.
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
username | String | Mandatory | Username of the enterprise | 100 | "test-enterprise" |
key | String | Mandatory | Unique API key provided by Clickpost for the enterprise | 100 | "92we9be5-3de8-4223-ad14-d7391159b80e" |
Payload
The payload will consist of the following fields:
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
pickup_info | Object | Mandatory | Information for where the shipment will be picked up by the carrier | ||
drop_info | Object | Mandatory | Information for where the shipment will be delivered by the carrier | ||
shipment_details | Object | Mandatory | Information about the shipment itself | ||
additional | Object | Optional | Additional optional information about the shipment |
Pickup Info (pickup_info
)
pickup_info
)This mandatory object takes in the data for the warehouse/pickup location for the shipment.
Note: Conditional Mandatory means certain carrier need this field mandatorily while other carrier do not need it at all.
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
pickup_lat | Float | Conditional Mandatory | Latitude of the pickup location. To review conditional mandatory refer to this doc here | 45.12211 | |
pickup_long | Float | Conditional Mandatory | Longitude of the pickup location | 88.12342 | |
pickup_name | String | Mandatory | Contact name of the consignor of the shipment | 100 | "Mukesh Kumar" |
pickup_organisation | String | Optional | Name of the organisation | 100 | "Walmart" |
pickup_address | String | Mandatory | Address of the pickup location | 500 | "123, ABC Street" |
pickup_district | String | Optional | District of the pickup location | 100 | "Nadia" |
pickup_city | String | Mandatory | City of the pickup location | 100 | "Mumbai City" |
pickup_state | String | Mandatory | State/province of the pickup location | 100 | "Maharashtra" |
pickup_landmark | String | Optional | Landmarks to help find the pickup location | 500 | "Near XYZ Towers" |
email | String | Mandatory | Email of the pickup contact | 50 | "[email protected]" |
pickup_phone | String | Mandatory | Contact number of the pickup contact | 11 | "9876543210" |
pickup_time | String | Mandatory | Time of pickup for the order (to be provided in YYYY-MM-DDTHH:MM:SS format only) | 2022-01-10T10:02:33 | |
pickup_pincode | String | Mandatory | 6-digit Pin code of the pickup location | 6 | "400065" |
pickup_country | String | Mandatory | Alpha ISO-2 country code of the pickup location. Only "IN" is accepted as input. | 2 | "IN" |
tin | String | Mandatory | Taxpayer Identification Number (TIN) of the seller. In case the TIN is not available, the user may choose to enter the seller's GST number instead. | 100 | "TIN00001" |
pickup_address_type | String | Optional | Address type of the pickup address. Must be either OFFICE or RESIDENTIAL | 10 | "OFFICE" |
Drop Info (drop_info
)
drop_info
)This mandatory object takes in the data for the delivery/consignee location for the shipment.
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
drop_lat | Float | Optional | Latitude of the drop location | 45.12211 | |
drop_long | Float | Optional | Longitude of the drop location | 88.12342 | |
drop_name | String | Mandatory | Contact name of the consignee of the shipment | 100 | "Mukesh Kumar" |
drop_organisation | String | Optional | Name of the organisation | 100 | "Walmart" |
drop_address | String | Mandatory | Address of the drop location | 500 | "123, ABC Street" |
drop_district | String | Optional | District of the drop location | 100 | "Mumbai City" |
drop_city | String | Mandatory | City of the drop location | 100 | "Mumbai" |
drop_state | String | Mandatory | State/province of the drop location | 100 | "Maharashtra" |
drop_landmark | String | Optional | Landmarks to help find the drop location | 500 | "Near XYZ Towers" |
drop_email | String | Optional | Email of the drop contact | 50 | "[email protected]" |
drop_phone | String | Mandatory | Contact number of the drop contact | 11 | "9876543210" |
drop_start_time | String | Optional | Estimated time of drop for the order (to be provided in YYYY-MM-DDTHH:MM:SS format only) Supported for Bluedart and Shipsy only. | 2022-01-10T10:02:33 | |
drop_end_time | String | Optional | Estimated end-time of drop for the shipment. (to be provided in YYYY-MM-DDTHH:MM:SS format only) Supported for Bluedart and Shipsy only. | 2022-01-10T12:02:33 | |
drop_pincode | String | Mandatory | 6-digit Pin code of the drop location | 6 | "400065" |
drop_country | String | Mandatory | Alpha ISO-2 country code of the drop location. Only "IN" is accepted as input. | 2 | "IN" |
drop_address_type | String | Optional | Address type of the drop address. Must be either OFFICE or RESIDENTIAL | 10 | "OFFICE" |
drop_vendor_code | String | Optional | Hub code of the drop address (if the drop address is a warehouse) | 50 | "test_drop_warehouse" |
location_type | String | Optional | Type of standardized address. Possible values include: What3Words | 50 | "What3Words" |
location_value | String | Optional | Value of the standardized address type selected in the location_type field.If What3Words, then the value of the What3Words address. | 500 | "stickler.leaky.workers" |
Additional Fields (additional
)
additional
)In the "additional" object optional fields can be passed which may be used by the carrier, or give additional details for the order, e.g. Async/Sync order creation or whether label generation is needed.
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
async | Boolean | Optional | Whether the order will be placed asynchronously (in the background) or not (in real-time). Defaults to false . Please read the section "Processing Async Requests" for how async requests work. | ||
label | Boolean | Optional | Whether label is required for the order or not. Defaults to true . | ||
zone | String | Optional | Zone of the location of pickup | 100 | "XYZ Locality" |
min_edd | Integer | Optional | Minimum estimated due date (in days) for delivery of the shipment | 5 | |
max_edd | Integer | Optional | Maximum estimated due date (in days) for delivery of the shipment | 10 | |
invoice_base_64 | String | Optional | A Base64 string representation of the invoice document file | 5000 | |
is_multi_seller | Boolean | Conditional | Required for multi-seller shipments only. Denotes whether the shipment has multiple items, each with different GST numbers. Defaults to false | ||
vendor_code | String | Optional | Vendor code of pickup location. Not supported for all carriers | 100 | "TESTWAREHOUSE-01" |
qc_type | String/Null | Optional | Only applicable for RVP. Should be set to doorstep if the carrier needs to do a quality check for the item, otherwise null . | 10 | "doorstep" |
rvp_reason | String | Conditional | Reason for returning the product/failed delivery. Mandatory if delivery_type is RVP. | 500 | "Defect in product" |
order_date | String | Optional | Date when the order was placed for this shipment. To be provided in YYYY-MM-DD format onlyCan also be sent in the DateTime format i.e. YYYY-MM-DDTHH:MM:SS | 50 | "2022-12-15" or "YYYY-MM-DDTHH:MM:SS" |
store_code | String | Optional | For customers using the store flow, they shall pass the store_code for the order to link the order with the respective store | 50 | "store-1" |
user_defined_field_array | List | Optional | This object provides additional fields to the customers who wish to add custom details to their labels configured on Clickpost. The field values mentioned here can be accessed via the udf_1 , udf_2 , udt_3 and udt_4 tags in the Label Configuration section on Clickpost dashboard.This list can only accept at max 10 objects. | [ { "name":"udf_1", "type":"String", "value":"" }, { "name":"udf_2", "type":"String", "value":"" }] | |
estimated_delivery_date | Date | Optional | The 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 | 2023-12-05 |
Return Info (return_info
)
return_info
)In the optionalreturn_info
object, the details for the return address is to be provided. The details are particularly useful in case of a failed delivery or product return due to other reasons.
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
lat | Float | Optional | Latitude of the return location | 45.12211 | |
long | Float | Optional | Longitude of the return location | 88.12342 | |
name | String | Mandatory | Contact name of the return contact of the shipment | 100 | "Mukesh Kumar" |
address | String | Mandatory | Address of the return location | 500 | "123, ABC Street" |
district | String | Optional | District of the return location | 100 | "Mumbai City" |
city | String | Mandatory | City of the return location | 100 | "Mumbai" |
state | String | Mandatory | State/province of the return location | 100 | "Maharashtra" |
landmark | String | Optional | Landmarks to help find the return location | 500 | "Near XYZ Towers" |
email | String | Optional | Email of the return contact | 50 | "[email protected]" |
phone | String | Mandatory | Contact number of the return contact | 11 | "9876543210" |
pincode | String | Mandatory | 6-digit Pin code of the return location | 10 | "400065" |
country | String | Mandatory | Alpha ISO-2 country code of the return location. Only "IN" is accepted as input. | 2 | "IN" |
User Defined Custom Fields ( user_defined_field_array
)
user_defined_field_array
)This object takes in upto 4 custom fields that can be shared in the payload to Clickpost. These values are not saved and are only used incase some dynamic data needs to be added to the custom labels created by the Clickpost's system. This object is passed inside the additional
object.
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
name | String | Mandatory | Name of the custom field. | 100 | "Speed" |
type | String | Mandatory | Currently, only value that should be sent here is "String" | 100 | "String" |
value | String | Mandatory | Value that you wish to allocate to the key name | 100 | "EDD" |
Shipment Details (shipment_details
)
shipment_details
)In the 'shipment_details' field, the details regarding all items, and important order details like payment type, order type, carrier, etc. are added.
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
items | List | Mandatory | List of items to be delivered in the shipment. Details of the items explained below. | ||
account_code | String | Mandatory | Courier partner account name configured on the Clickpost dashboard. Will return a 400 Bad Request response if the given account is inactive or does not exist. | 100 | 'test_courier' |
height | Integer | Mandatory | Height of the overall package (in cms) | 25 | |
breadth | Integer | Mandatory | Width of the overall package (in cms) | 45 | |
length | Integer | Mandatory | Length of the overall package (in cms) | 75 | |
weight | Integer | Mandatory | Weight of the package (in gms) | 500 | |
courier_partner | Integer | Mandatory | Each carrier partner has a unique identifier (Integer value) in the Clickpost system, which will be used to identify the courier partner and track the shipment. List: http://track.clickpost.in/courier_partner | 123 | |
reference_number | String | Mandatory | Reference number of the order. Must be unique for every shipment, i.e. every call of this API. Note: For Bluedart, the reference number should not go beyond 20 characters, or else the AWB generation will fail | 20 | "TEST12345678912345678912" |
cod_value | Float | Conditional Mandatory | Cash to be given to the carrier (currency to be determined by currency_code ). Must be non-zero for COD orders, and zero for PREPAID orders. | 25.25 | |
order_id | String | Optional | Identification string for the order | 100 | "TestOrderID00001" |
order_type | String | Mandatory | Type of payment of the shipment. Can only take values "COD", "EXCHANGE" or "PREPAID". cod_value must be non-zero for COD shipments and zero for PREPAID shipments. "EXCHANGE" is only applicable for Delhivery (Partner ID: 4) and Bluedart (Partner ID: 5) | 10 | "COD"/"PREPAID"/"EXCHANGE" |
delivery_type | String | Mandatory | Type of delivery to be done. Can only take values "FORWARD" or "RVP". | 10 | "FORWARD"/"RVP" |
invoice_value | Float | Mandatory | Value of the shipment as mentioned in the invoice. | 256.29 | |
invoice_date | String | Mandatory | Date of issuance of the invoice of the shipment. (YYYY-MM-DD format only) | 100 | 2022-01-10 |
awb_number | String | Conditional Mandatory | The airwaybill number of the shipment. Mandatory for the following couriers - Shadowfax Forward (Partner ID: 9) - Fareye (Partner ID: 31) - Gati (Partner ID: 32) - SELF Reverse (Partner ID: 34) - SELF (Partner ID: 35) - Gati MPS (Partner ID: 71) - Holisol Reverse (Partner ID: 77) - Trackon (Partner ID: 80) - Sicepat (Partner ID: 116) - Ithink Logistics (Partner ID: 170) - Swftbox (Partner ID: 202) - KerryIndev MPS (Partner ID: 259) | 100 | "TESTAWB0001" |
Reference Number should not exceed 20 characters
For Bluedart, the reference number should not go beyond 20 characters, or else the AWB generation will fail
Item Level details (items
)
items
)The details for each item to be delivered is passed in the "items" field, in "shipment_details".
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
description | String | Mandatory | Brief description of the item | 500 | "Brown Cotton Socks - 1 pair" |
quantity | Integer | Mandatory | Number of units of the item | 5 | |
weight | Float | Mandatory | Weight of each unit of the item | 500 | |
price | Float | Mandatory | Non-negative price of each unit of the item (currency to be decided by 'currency_code' field) | 64.99 | |
gst_info | Object | Conditional | Required for multi-seller shipments Information regarding the GST levied on the item. GST Info to be passed will have the same fields as the gst_info field mentioned below. | ||
final_amount_paid | String | Optional | The Final amount that the customer has paid for the item after deducting store credits, discounts, vouchers etc | 100 | "200.00" |
store_credits_used | String | Optional | The store credits used to purchase the item | 100 | "50.50" |
product_id | String | Conditional Optional | Needed only if customer has subscribed for Exchanges platform (Currently only supported for Shopify) Product ID of the item in Shopify storefront | 100 | "4817825955902" |
variant_id | String | Conditional Optional | Needed only if customer has subscribed for Exchanges platform (Currently only supported for Shopify) Variant ID of the item (mentioned in product_id ) in Shopify storefront | 100 | "32783884976190" |
additional | Object | Conditional | Additional details regarding the item |
The item's additional
object can have the following fields:
Field Name | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
cat | String | Optional | Category of the item in question | 50 | Footwear |
manufacture_country_code | String | Optional | Alpha-2 ISO Country code of manufacture of the item | 2 | "CA" |
manufacture_country | String | Optional | Full country name of manufacture of the item | 100 | "Canada" |
sku | String | Optional | Stock-keeping unit of the item | 100 | "SKU0001" |
return_days | Integer | Optional | Number of days within which the item can be returned | 5 | |
exchange_days | Integer | Optional | Number of days within which the item can be exchanged | 5 | |
product_url | String | Optional | URL for the product. If there are multiple URLs, they can be sent as a single string with comma-separated values. | 1000 | "http://link1.to.product, http://link2.to.product" |
images | String | Optional | URL for the image(s) of the product. If there are multiple URLs, they can be sent as a single string with comma-separated values. | 1000 | "http://link.to.product.image1, http://link.to.product.image2" |
color | String | Conditional Optional | Colour of the item Applicable for quality checking for RVP shipments | 100 | "dark blue" |
sub_category | String | Conditional Optional | Category the item's type is classified in Applicable for quality checking for RVP shipments | 100 | "T-Shirts" |
size | String | Conditional Optional | Size of the item Applicable for quality checking for RVP shipments | 100 | "XL" |
brand | String | Conditional Optional | Brand of the item Applicable for quality checking for RVP shipments | 100 | "Puma" |
return_reason | String | Conditional Optional | Reason for returning the item Applicable for quality checking for RVP shipments | 100 | "Defective product" |
special_instructions | String | Conditional Optional | Special Instructions for returning the item Applicable for quality checking for RVP shipments | 100 | "Handle with care" |
imei | String | Conditional Optional | IMEI number of the item (if it is a mobile device) Applicable for quality checking for RVP shipments | 100 | "12345678910111" |
ean | String | Conditional Optional | EAN Number of the item Applicable for quality checking for RVP shipments | 100 | "EAN111111" |
height | Integer | Mandatory | Height of one unit of the item (in cms) | 25 | |
breadth | Integer | Mandatory | Width of one unit of the item (in cms) | 45 | |
length | Integer | Mandatory | Length of one unit of the item (in cms) | 75 | |
weight | Integer | Mandatory | Weight of one unit of the item (in gms) | 500 |
GST Info (gst_info
)
gst_info
)This object encapsulates every information about the Goods and Services Tax (GST) levied on the shipment, and all it's requisite details, e.g. GST Number, EWaybill Number, etc.
Field | Data Type | Field | Description | Max Length | Example |
---|---|---|---|---|---|
enterprise_gstin | String | Optional | GST No of enterprise shipping the shipment | 100 | |
seller_gstin | String | Optional | GST No of seller sending the shipment (will be different from above for marketplaces) | 100 | |
taxable_value | Float | Optional | Taxable amount for GST (in INR) | ||
ewaybill_serial_number | String | Optional | EWaybill Serial Number for the shipment | 100 | |
is_seller_registered_under_gst | Boolean | Optional | Whether the enterprise/seller is registered under the GST law | ||
place_of_supply | String | Optional | Place of supply of the service or product. Please refer to https://cleartax.in/s/gst-state-code-jurisdiction for further details | 100 | "DELHI" |
gst_discount | Float | Optional | Discount under GST, if any | ||
hsn_code | String | Optional | Harmonized System Nomenclature Code of the product. Please refer to https://cleartax.in/s/gst-hsn-lookup for knowing the code for your products. | 50 | "1234.56.78" |
gst_total_tax | Float | Optional | Total GST applicable for the shipment (in INR) | 250.00 | |
sgst_tax_rate | Float | Optional | Tax percent applicable for SGST for the shipment | 25 | |
sgst_amount | Float | Optional | SGST Amount levied on the shipment (in INR) | 250.00 | |
igst_tax_rate | Float | Optional | Tax percent applicable for IGST for the shipment | 25 | |
igst_amount | Float | Optional | IGST Amount levied on the shipment (in INR) | ||
cgst_tax_rate | Float | Optional | Tax percent applicable for CGST for the shipment | ||
cgst_amount | Float | Optional | CGST Amount levied on the shipment (in INR) | ||
consignee_gstin | String | Conditional | GST No of consignee (compulsory for B2B shipments) |
Response
The response typically consists of the following fields. Keep in mind that additional fields can be present according to the requirement of the enterprise/carrier.
Field Name | Data Type | Description |
---|---|---|
meta | Object | Metadata for the request, e.g. status code, error messages. |
result | Object | The actual result of the request |
order_id | Integer | Order ID of the request [For internal use of Clickpost for debuggging] |
tracking_id | Integer | A shipment ID of the request [For internal use of Clickpost for debuggging] |
Response Meta
Field Name | Data Type | Description |
---|---|---|
status | Integer | Status code for the request (including but not limited to HTTP Status codes) |
message | String | Error/Success messages for the request |
success | Boolean | Whether the order was successfully created or not |
username | String | your Clickpost username with which you tried creating the order |
reference_number | String | reference_number passed in the request. Please share this number with Clickpost team to debug any issue with the request |
Response Result
Field Name | Data Type | Description |
---|---|---|
waybill | String | Waybill of the newly created order. This waybill is automatically registered for tracking in our database |
reference_number | String | Reference number of the order, sent in the payload. |
label | String/Null | URL to the generated label of the order. If labels are not needed, this stays null. |
commercial_invoice_url | String | (Appears for certain carriers) URL to the generated commercial invoice of the order |
courier_partner_id | Integer | ID of the carrier |
courier_name | String | Name of the carrier |
sort_code | String/Null | Carrier Sort code. Certain carriers use something called a sort code that can be passed to the shipping label for custom-built labels. Will return null if sort codes are not supported. |
security_key | String | UUID security key of the shipment that needs to be stored at your end. Used to enable security features on the shipment |
order_id | String | order_id passed in the API request, else reference_number will reflect here if nothing is passed in the request |
account_code | String | account_code with which the order creation was done |
Sample Payload
{
"drop_info":{
"drop_lat":0,
"drop_city":"Mumbai",
"drop_long":0,
"drop_name":"dsadsad sadsad",
"drop_email":"[email protected]",
"drop_phone":"9876543210",
"drop_state":"Maharashtra",
"drop_address":"123 ABC St",
"drop_district":"Mumbai City",
"drop_landmark":null,
"drop_pincode":"400065",
"drop_country":"IN",
"drop_address_type":"RESIDENTIAL",
"location_type":"What3Words",
"location_value":"stickler.leaky.workers"
},
"pickup_info":{
"pickup_lat":25.1414664,
"pickup_city":"Mumbai",
"pickup_long":55.255369,
"pickup_name":"TEST DO NOT PICKUP",
"pickup_time":"2022-10-271T11:52:36+04:00",
"pickup_email":"[email protected]",
"pickup_phone":"1234567890",
"pickup_state":"Maharashtra",
"pickup_address":"123, ABC St",
"pickup_district":"Mumbai City",
"pickup_landmark":null,
"pickup_phone_code":"+971",
"pickup_pincode":"400065",
"pickup_country":"IN",
"pickup_address_type":"OFFICE"
},
"shipment_details":{
"items":[
{
"sku":"53813",
"price":249.29,
"weight":500,
"hs_code":"6405.10.00",
"quantity":1,
"description":"Tod's Blue Patent Cutout Ankle Strap Ballet Flats Size 39.5",
"manufacture_country":"Italy",
"manufacture_country_code":"IT",
"cat":"Footwear",
"color":"Blue",
"brand":"Allen Solly",
"size":"Small",
"final_amount_paid":"200.29",
"store_credits_used":"49.00",
"product_id":"11112222333444",
"variant_id":"55556666777888"
}
],
"height":13,
"length":23,
"weight":1000,
"breadth":31,
"order_id":"TESTORDER0001",
"cod_value":50,
"order_type":"COD",
"invoice_date":"2022-06-21",
"delivery_type":"FORWARD",
"invoice_value":468.58,
"invoice_number":"TLC-2022-06-WS-00038",
"courier_partner":"129",
"reference_number":"TESTORDER000001",
"account_code":"test"
},
"additional":{
"return_info":{
"lat":25.1414664,
"city":"Mumbai",
"long":55.255369,
"name":"TEST DO NOT RETURN",
"email":"[email protected]",
"phone":"1234567890",
"state":"Maharashtra",
"address":"123, ABC St",
"district":"Mumbai City",
"landmark":null,
"pincode":"400065",
"country":"IN"
},
"async":false,
"label":true,
"estimated_delivery_date":"2023-12-05",
"user_defined_field_array":[
{
"name":"udf_1",
"type":"String",
"value":""
},
{
"name":"udf_2",
"type":"String",
"value":""
},
{
"name":"udf_3",
"type":"String",
"value":""
},
{
"name":"udf_4",
"type":"String",
"value":""
}
]
},
"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
}
}
{
"drop_info":{
"drop_lat":0,
"drop_city":"Mumbai",
"drop_long":0,
"drop_name":"dsadsad sadsad",
"drop_email":"[email protected]",
"drop_phone":"9876543210",
"drop_state":"Maharashtra",
"drop_address":"123 ABC St",
"drop_district":"Mumbai City",
"drop_landmark":null,
"drop_pincode":"400065",
"drop_country":"IN",
"drop_address_type":"OFFICE",
"drop_vendor_code":"test_drop"
},
"pickup_info":{
"pickup_lat":25.1414664,
"pickup_city":"Mumbai",
"pickup_long":55.255369,
"pickup_name":"TEST DO NOT PICKUP",
"pickup_time":"2022-10-27T11:52:36",
"email":"[email protected]",
"pickup_phone":"1234567890",
"pickup_state":"Maharashtra",
"pickup_address":"123, ABC St",
"pickup_district":"Mumbai City",
"pickup_landmark":"Near XYZ Towers",
"pickup_pincode":"400065",
"pickup_country":"IN",
"tin":"TIN000001",
"pickup_address_type":"RESIDENTIAL"
},
"shipment_details":{
"items":[
{
"sku":"53813",
"price":249.29,
"weight":500,
"hs_code":"6405.10.00",
"quantity":1,
"description":"Tod's Blue Patent Cutout Ankle Strap Ballet Flats Size 39.5",
"product_id":"11112222333444555",
"variant_id":"66667777888999111",
"additional":{
"manufacture_country":"Italy",
"manufacture_country_code":"IT",
"cat":"Footwear",
"images":"http://link1.image.com",
"product_url":"http://link1.product.com,http://link2.procuct.com",
"return_days":2,
"exchange_days":2,
"length":25,
"breadth":15,
"height":11,
"brand":"Tod's",
"color":"blue",
"size":"39.5",
"serial_no":"25",
"imei":"AA-BBBBBB-CCCCCC-D",
"ean":"EAN123456",
"sub_category":"Flats",
"return_reason":"ABCD"
}
}
],
"height":13,
"length":23,
"weight":1000,
"breadth":31,
"order_id":"TESTORDER0001",
"cod_value":50,
"cod_currency_code":"INR",
"order_type":"COD",
"invoice_date":"2022-06-21",
"delivery_type":"RVP",
"invoice_value":468.58,
"invoice_number":"TLC-2022-06-WS-00038",
"courier_partner":3,
"reference_number":"TESTECOM00001",
"account_code":"1",
"reseller_name":"ABCD",
"booking_id":"123456"
},
"additional":{
"return_info":{
"lat":25.1414664,
"city":"Mumbai",
"long":55.255369,
"name":"TEST DO NOT RETURN",
"email":"[email protected]",
"phone":"1234567890",
"state":"Maharashtra",
"address":"123, ABC St",
"district":"Mumbai City",
"landmark":"Near GHI Towers",
"pincode":"400065",
"country":"IN"
},
"async":false,
"label":true,
"vendor_code":"ABC",
"zone":"ABC",
"min_edd":2,
"max_edd":5,
"invoice_base_64":"JWBERKLhjfswifniouNuiHFGIUEHWOWNOFOINkjno2749189",
"priority":"URGENT",
"is_multi_seller":false,
"channel_name":"Channel 1",
"exchange_address":"123, XYZ Street",
"exchange_city":"Delhi",
"exchange_state":"Delhi",
"exchange_country":"India",
"exchange_pincode":"110001",
"exchange_shipment_description":"Exchanged due to defective product",
"otp_based_delivery":false,
"inv_url":"http://link.to.invoice.com",
"pickup_type":"WH",
"is_fragile":true,
"is_dangerous":false,
"from_wh":"SOURCE WAREHOUSE",
"to_wh":"DESTINATION WAREHOUSE",
"template_id":"123456",
"template_category":"ABCD",
"invoice_reference":"TESTINV00001",
"categories":"Footwear, Footwear",
"otp_code":"174747",
"insured":false,
"customer_id_number":"111AAA6464646",
"insurance_amount":1125.55,
"exchange_rvp_awb":"TESTRVPAWB00001",
"rvp_reason":"Defective product",
"qc_type": "doorstep",
"order_date":"2022-11-21",
"user_defined_field_array":[
{
"name":"udf_1",
"type":"String",
"value":""
},
{
"name":"udf_2",
"type":"String",
"value":""
},
{
"name":"udf_3",
"type":"String",
"value":""
},
{
"name":"udf_4",
"type":"String",
"value":""
}
]
},
"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,
"cgst_tax_rate":100
}
}
{
"drop_info": {
"drop_lat": 0,
"drop_city": "Mumbai",
"drop_long": 0,
"drop_name": "dsadsad sadsad",
"drop_email": "[email protected]",
"drop_phone": "9876543210",
"drop_state": "Maharashtra",
"drop_address": "123 ABC St",
"drop_district": "Mumbai City",
"drop_landmark": null,
"drop_pincode": "400065",
"drop_country": "IN"
},
"pickup_info": {
"pickup_lat": 25.1414664,
"pickup_city": "Mumbai",
"pickup_long": 55.255369,
"pickup_name": "TEST DO NOT PICKUP",
"pickup_time": "2022-10-271T11:52:36+04:00",
"pickup_email": "[email protected]",
"pickup_phone": "1234567890",
"pickup_state": "Maharashtra",
"pickup_address": "123, ABC St",
"pickup_district": "Mumbai City",
"pickup_landmark": null,
"pickup_pincode": "400065",
"pickup_country": "IN"
},
"shipment_details": {
"items": [
{
"sku": "53813",
"price": 249.29,
"weight": 500,
"hs_code": "6405.10.00",
"quantity": 1,
"description": "Tod's Blue Patent Cutout Ankle Strap Ballet Flats Size 39.5",
"manufacture_country": "Italy",
"manufacture_country_code": "IT",
"cat": "Footwear",
"product_id": "111122223333444",
"variant_id": "555566667777888"
}
],
"height": 13,
"length": 23,
"weight": 1000,
"breadth": 31,
"order_id": "TESTORDER0001",
"cod_value": 50,
"order_type": "COD",
"invoice_date": "2022-06-21",
"delivery_type": "FORWARD",
"invoice_value": 468.58,
"invoice_number": "TLC-2022-06-WS-00038",
"courier_partner": "129",
"reference_number": "TESTORDER000001",
"account_code": "test"
},
"additional": {
"return_info": {
"return_lat": 25.1414664,
"return_city": "Mumbai",
"return_long": 55.255369,
"return_name": "TEST DO NOT RETURN",
"return_email": "[email protected]",
"return_phone": "1234567890",
"return_state": "Maharashtra",
"return_address": "123, ABC St",
"return_district": "Mumbai City",
"return_landmark": null,
"return_pincode": "400065",
"return_country": "IN"
},
"async": true,
"label": true,
"vendor_code": "ABC",
"user_defined_field_array":[
{
"name":"udf_1",
"type":"String",
"value":""
},
{
"name":"udf_2",
"type":"String",
"value":""
},
{
"name":"udf_3",
"type":"String",
"value":""
},
{
"name":"udf_4",
"type":"String",
"value":""
}
]
},
"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,
"cgst_tax_rate": 100
}
}
Sample Response
We can either get a 200 (OK) or a 400 (Bad Request) error as follows
{
"meta": {
"status": 200,
"message": "Order Placed Successfully",
"success": true,
"username": "test-user",
"reference_number": "TEST-20230428"
},
"result": {
"label": "https://clickpost-shipping-label.s3.amazonaws.com:443/ECOM/TEST-20230428.pdf",
"waybill": "4600001ASDF",
"order_id": "TEST-Order-ID",
"sort_code": "MH/WHH/BMF",
"account_code": "EcomExpress Forward",
"courier_name": "EcomExpress",
"security_key": "2e43f762-0c7c-41ef-ges5-20a3cc7aascw",
"reference_number": "TEST-20230428",
"courier_partner_id": 3
},
"order_id": 199649298,
"tracking_id": 6790638236
}
{
"meta": {
"status": 400,
"message": "Error Message",
"success": false,
"username": "test-user",
"reference_number": "TEST-20230428"
}
}
{
"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,
"username": "test-user",
"reference_number": "TEST-ALPHA-132135"
}
}
{
"meta": {
"success": true,
"message": "Order Placed Successfully",
"status": 202,
"username": "test-user",
"reference_number": "TEST-ALPHA-132135"
},
"order_id": 8488542,
"result": {
"reference_number": "TEST-ALPHA-132135",
"waybill": null,
"label": null,
"sort_code": null
}
}
Possible Error Codes
These are the list of possible error/status codes that can appear in the response metadata, and the actionables corresponding to each.
Meta Status Code | HTTP Status Code | Description | Actionable | Order Successful? | Status Message |
---|---|---|---|---|---|
102 | 200 | For async orders: The order has been recorded in Clickpost's database and is under processing. | Need to re-attempt Clickpost's order creation API to check if the order has been processed. | No | " |
200 | 200 | The order is successfully created | None | Yes | "Success" |
202 | 200 | For async orders: The async order request has been successfully registered. | Need to poll the same API endpoint with the same reference number (the one used to register the order) to get the results of the request. | Order may succeed or fail | "Order Registered Successfully" |
301 | 200 | The customer is sending an invalid/non-existent/inactive license key in the URL parameters | Need to re-attempt the order with a valid/registered/active license key, or check the username. | No | "Authentication Failed: Invalid Token or API Key" |
302 | 200 | Either of the three things: - The customer is sending the courier_partner value as a string- The customer is sending a null value in the courier_partner field.- The partner ID being sent in courier_partner field does not exist. | Need to re-attempt the order with a valid integer value in the courier_partner field, and the value should exist in Clickpost's database. | No | "Invalid Courier Partner Id with Field courier_partner" |
303 | 200 | For async orders: The awb_number provided already exists and is registered by Clickpost | Need to re-attempt the order with a different awb_number value. | Yes | "Waybill already registered" |
307 | 200 | Theorder_type value is anything other than PREPAID , COD or EXCHANGE , or is null . | Need to re-attempt the order with the order_type as either PREPAID , COD or EXCHANGE . | No | "You have entered invalid Order Type" |
308 | 200 | Thepriority value is anything other than NORMAL or URGENT . | Need to re-attempt the order with the priority as either NORMAL or URGENT . | No | "You have entered invalid Order priority" |
309 | 200 | Thedelivery_type value is anything other than FORWARD or RVP . | Need to re-attempt the order with the delivery_type as either FORWARD or RVP . | No | "Invalid Delivery Type" |
310 | 200 | In case of RVP orders: This is due to either of the following - The rvp_reason field is missing- The rvp_reason length is more than 500 characters. | Need to re-attempt the RVP order with a non-null rvp_reason value within 500 characters. | No | "RVP reason is missing" or "RVP reason can't be more than 500 chars" |
311 | 200 | For RVP orders: The carrier defined by the courier_partner field does not support RVP shipments, or is not an RVP carrier. | Need to re-attempt the RVP order with a courier_partner value that supports RVP shipments. | No | "Invalid Courier Partner For RVP" |
312 | 200 | There is no item data in the payload (in the item field). | Need to retry the order with a non-empty items array. | No | "Items Data is missing from order details" |
313 | 200 | Either of the following: - The item data being sent in the items field is either a string or any other invalid format.- The items value is an array, but of anything other than objects.- The items value is an array of objects, but one or more mandatory fields are missing for one or more items. | Need to retry the order with proper items data, as an array of JSON objects. | No | "Invalid Format of items for Order data" |
314 | 200 | There is an issue with the order data being passed. | The error is captured in the status message. Retry the order after addressing the status message. | No | "Invalid Format of items for Order data: " |
315 | 200 | Either of the following: - For a PREPAID order, the cod_value is non-zero.- For a COD order, the cod_value is zero. | Need to retry the orders after: - (For PREPAID orders) setting the cod_value to zero.- (For COD orders) setting the cod_value to a non-zero number | No | "Invalid Cod Value" |
316 | 200 | There are no credentials for the carrier of the account given in account_code , or the credentials are blank. | Need to re-attempt the order with a different account_code , or fill the credential fields in the dashboard and retry. | No | "You do not have credentials for the Courier Partner" |
319 | 200 | There is an issue in placing orders with the carrier. | The actual error generally pops up alongside the error message (see Status Message). In cases where the error message is vague, contact the support team. | No | "Error In Order Placing To Courier Partner: " |
320 | 200 | The enterprise has not subscribed for Clickpost's Order Creation Service. | Need to subscribe to the order creation service, then retry with all valid details and credentials. | No | "This service is not subscribed by you" |
321 | 200 | The awb provided in the awb_number field does not exist in Clickpost's database. | Need to provide a registered AWB, or remove the AWB field and try again. | No | "Awb Number Does not exist in system for courier partner" |
322 | 200 | There is an issue in the carrier's servers. | Need to retry after waiting for a while, or get in touch with Clickpost support or the carrier's support. | No | "Internal Server Error In Courier Partners Server" |
323 | 200 | An order is already present in Clickpost's database with the same reference number as the one provided. | Need to re-attempt the order with a different reference number | Yes | "You have already placed this order" |
328 | 200 | Some mandatory field in the POST data might be missing. | Check for missing fields that are supposed to be there in the data and retry | No | "Invalid POST data" |
329 | 200 | The connection to the carrier's API timed out. | Need to retry after waiting for a while, or get in touch with Clickpost support or the carrier support. | No | "Courier Partner API timeout" |
351 | 200 | The account name of the carrier account given in the account_code field does not exist for the enterprise user. | The user needs to check either/all of the things below if they are correct - Enterprise license key in the URL params - Carrier ID in the courier_partner field.- Account name in the account_code field, and whether this account exists for this carrier.Re-attempt the order after correcting any of the incorrect details mentioned above. | No | "Clickpost Account: Does not exist" |
352 | 200 | There are multiple accounts of the same enterprise with the same carrier with the same name as the one in account_code field. | No | "Multiple account exists" | |
353 | 200 | The account mentioned in the account_code field is inactive. | Need to either enable the account on the dashboard from the enterprise's end, or use an active account. | No | "Clickpost Account: Inactive" |
354 | 200 | There is an unhandled error from the carrier's end. | The error is typically visible in the status message and can be fixed accordingly. In case of vague error messages, get in touch with the support team | No | "Unhandled error! Contact [email protected]" or the actual error |
355 | 200 | In certain couriers the vendor_code field is required. This error pops up whenever vendor_code is not passed in the payload | Need to pass the vendor_code field alongwith a registered vendor code. | No | "Vendor code not found" |
400 | 200 | There is an issue with the payload, or some invalid data is being sent in the request. | Need to fix the issues in the payload as mentioned in the status message. If "Bad Request" pops up, get in touch with the support team. | No | "Bad Request" or the actual error |
500 | 200 | There is an error in Clickpost's servers. | Need to wait a while and try again. If this error pops up even after multiple tries, get in touch with the support team. | No | "Oops! Internal server error in Clickpost" |
Updated 2 months ago