New B2B MPS Order Creation API

This API is intended for creating B2B Multi Piece shipments within India.

Overview

To create B2B shipments with domestic (Indian) couriers, Clickpost has provided the Order Creation API that caters specifically to Indian customers and couriers. Enterprises can place Multi-Piece Shipments with this API, to be delivered by their preferred courier partner.

Features in new API

This API is an upgrade over the existing MPS API and offers much more functionality.

  1. Users can provide details of multiple invoices per shipment. With each invoice they can provide- invoice_number, invoice_date, invoice_value, ewaybill number, ewaybill expiry date and invoice_base_64. Users can also link multiple invoices to a box.
  2. Users can provide details of multiple purchase orders per shipment. With each PO they can provide purchase order number and purchase order expiry date. Users can also link multiple purchase orders to a box.
  3. Dedicated fields for taking appointment details like appointment id, date and time. Automated emails can be sent to the carrier POC if these details are received and the appointment module is configured.

API Flow and Structure


This API by default works in async mode. This means that initially you will only get an acknowledgement that the response has been received. You will have to poll the API using the GET function frequently to check if the order was created successfully or not. Read more here.

However, if you don't want the labels and box sticker then you can call the API in sync mode.To do so keep the is_async, is_box_sticker_required and is_label_required fields as false.

Geography

This is a standard API which supports all shipments created and transported within India.

Path

POST <https://www.clickpost.in/api/v1/create-b2b-order/?username=testABC&key=******>

Query Params

Query Parameters to be passed directly in the URL.

Field NameData TypeFieldDescriptionMax LengthExample
usernameStringMandatoryUsername of the enterprise100"test-enterprise"
keyStringMandatoryUnique license key provided by Clickpost for the enterprise (This string is a UUID)100"Test-key"

Sample Payload and Postman Collection

Run in Postman

{
   "pickup_info": {
       "name": "Mr Ramesh",
       "phone": "999999999",
       "district": "Chennai",
       "city": "Chennai",
       "landmark": "test_landmark",
       "organisation": "test_organisation",
       "state": "TamilNadu",
       "time": "2022-10-27T11:52:36+0530",
       "pincode": "600034",
       "country": "India",
       "address_type": "",
       "address": "NEW NO.150 OLD NO.60,RAMA Naiken STREET, Nungambakkam",
       "email": "[email protected]",
       "vendor_code": "teste_vendor_code",
       "location_code": "",
       "tin": "test"
   },
   "drop_info": {
       "organisation": "test_organisation",
       "district": "Puducherry",
       "address_type": "",
       "vendor_code": "",
       "name": "Mr Himesh",
       "landmark": "test_landamrk",
       "phone": "999999999",
       "email": "[email protected]",
       "city": "Puducherry",
       "state": "Puducherry",
       "pincode": "605001",
       "country": "India",
       "location_code": "",
       "address": "104, Kamaraj Salai, "
   },
   "shipment_info": {
       "description": "This is a big shipment",
       "reference_number": "TEST-112212932",
       "courier_partner": 129,
       "account_code": "Bluedart-prod1",
       "cod_value": 0,
       "order_type": "PREPAID",
       "order_id": "TESTorder_id1",
       "delivery_type": "FORWARD",
       "weight": 3000,
       "invoice_info": [
           {
               "number": "inv-1",
               "value": 10000,
               "date": "2024-09-30",
               "base64": "",
               "ewaybill_serial_number": null,
               "ewaybill_expiry_date": null,
               "description": "Contains 36 qty"
           },
           {
               "number": "inv-2",
               "value": 10000,
               "date": "2024-09-30",
               "base64": "",
               "ewaybill_serial_number": null,
               "ewaybill_expiry_date": null,
               "description": "Contains 36 qty"
           }
       ],
       "purchase_order_info": [
           {
               "number": "po-1",
               "expiry_date": "2024-09-30"
           },
           {
               "number": "po-2",
               "expiry_date": "2024-09-30"
           }
       ],
       "asn_info": [
           {
               "asn_number": "asn-1",
               "asn_date": "2024-09-30"
           }
       ],
       "box_info": [
           {
               "count": 5,
               "reference_number_prefix": "ABC",
               "code": "",
               "height": 10,
               "length": 10,
               "weight": 10,
               "breadth": 10,
               "description": "test description",
               "purchase_order_info": [
                   {
                       "number": "po-1"
                   }
               ],
               "invoice_info": [
                   {
                       "number": "inv-2"
                   }
               ],
               "product_info": [
                   {
                       "sku": "test_sku",
                       "sku_count": "2",
                       "description": "test description",
                       "product_category": "",
                       "manufacturer_country": "",
                       "manufacturer_country_code": "",
                       "hsn_code": "",
                       "price": 10000
                   },
                   {
                       "sku": "test_sku",
                       "sku_count": "2",
                       "description": "test description",
                       "product_category": "",
                       "manufacturer_country": "",
                       "manufacturer_country_code": "",
                       "hsn_code": "",
                       "price": 10000
                   }
               ]
           },
           {
               "count": 5,
               "reference_number_prefix": "CDF",
               "height": 10,
               "length": 10,
               "weight": 10,
               "breadth": 10,
               "description": "test description2",
               "purchase_order_info": [
                   {
                       "number": "po-1"
                   },
                   {
                       "number": "po-2"
                   }
               ],
               "invoice_info": [
                   {
                       "number": "inv-1"
                   },
                   {
                       "number": "inv-2"
                   }
               ],
               "product_info": [
                   {
                       "sku": "test_sku",
                       "sku_count": "2",
                       "description": "test description",
                       "product_category": "",
                       "manufacturer_country": "",
                       "manufacturer_country_code": "",
                       "hsn_code": "",
                       "price": 10000
                   },
                   {
                       "sku": "test_sku",
                       "sku_count": "2",
                       "description": "test description",
                       "product_category": "",
                       "manufacturer_country": "",
                       "manufacturer_country_code": "",
                       "hsn_code": "",
                       "price": 10000
                   }
               ]
           }
       ],
       "gst_info": {
           "seller_gstin": "",
           "enterprise_gstin": "",
           "taxable_value": 0,
           "is_seller_registered_under_gst": null,
           "place_of_supply": "",
           "gst_discount": 0,
           "gst_total_tax": 0,
           "sgst_tax_rate": 0,
           "sgst_amount": 0,
           "igst_tax_rate": 0,
           "igst_amount": 0,
           "cgst_tax_rate": 0,
           "cgst_amount": 0,
           "consignee_gstin": "",
           "sgst_total_tax": 0
       },
       "products_in_shipment": [
           {
               "sku": "test_sku",
               "sku_count": "2",
               "description": "test description",
               "product_category": "",
               "manufacturer_country": "",
               "manufacturer_country_code": "",
               "hsn_code": "",
               "price": 10000
           },
           {
               "sku": "test_sku",
               "sku_count": "2",
               "description": "test description",
               "product_category": "",
               "manufacturer_country": "",
               "manufacturer_country_code": "",
               "hsn_code": "",
               "price": 10000
           }
       ]
   },
   "appointment_info": {
       "start_time": "2023-05-24T10:00:00+0530",
       "end_time": "2023-05-24T12:00:00+0530",
       "id": ""
   },
   "additional_info": {
       "return_info": {
           "lat": 20.45,
           "long": 40.54,
           "name": "CL-FC-CHN-PGR-Packing",
           "phone": "999999999",
           "district": "test_district",
           "city": "Chennai",
           "landmark": "test_landmark",
           "organisation": "test_organisation",
           "state": "TamilNadu",
           "time": "2022-10-27T11:52:36",
           "pincode": "600034",
           "country": "India",
           "address_type": "",
           "address": "NEW NO.150 OLD NO.60,RAMA Naiken STREET, Nungambakkam",
           "email": "[email protected]",
           "vendor_code": "teste_vendor_code",
           "location_code": "",
           "tin": "test"
       },
       "is_label_required": true,
       "is_box_sticker_required": true,
       "is_multi_seller": false,
       "is_async": true,
       "zone": "",
       "order_date": "2024-10-11",
       "store_code": "",
       "user_defined_field_array": [
           {
               "name": "udf_1",
               "type": "String",
               "value": ""
           }
       ]
   }
}


Payload Description

The payload will consist of the following 5 high level sections:

Field NameData TypeField TypeDescriptionMax LengthExample
pickup_infoObjectMandatoryInformation for where the shipment will be picked up by the courier
drop_infoObjectMandatoryInformation for where the shipment will be delivered by the courier
shipment_infoObjectMandatoryInformation about the shipment itself
additional_infoObjectOptionalAdditional optional information about the shipment
appointment_infoObjectOptionalInformation for appointment based deliveries.

Pickup Info (pickup_info)

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

Field NameData TypeField TypeDescriptionMax LengthExample
latFloatOptionalLatitude of the pickup location45.12211
longFloatOptionalLongitude of the pickup location88.12342
nameStringMandatoryContact name of the consignor of the shipment100"Mukesh Kumar"
organisationStringMandatoryName of the organisation100"Walmart"
addressStringMandatoryAddress of the pickup location500"123, ABC Street"
districtStringOptionalDistrict of the pickup location100"Nadia"
cityStringMandatoryCity of the pickup location100"Mumbai City"
stateStringMandatoryState/province of the pickup location100"Maharashtra"
landmarkStringOptionalLandmarks to help find the pickup location500"Near XYZ Towers"
emailStringMandatoryEmail of the pickup contact50"[email protected]"
phoneStringMandatoryContact number of the pickup contact11"9876543210"
timeStringMandatory

Time of pickup for the order (to be provided in YYYY-MM-DDTHH:MM:SS format only)

For IST, keep the time in IST and add +0530

So if the pickup time is 2pm IST then it should be written as 2022-01-10T14:00:00+0530

2022-01-10T10:02:33+0530
pincodeStringMandatory6-digit Pin code of the pickup location6"400065"
countryStringMandatoryAlpha ISO-2 country code of the pickup location. Only "IN" is accepted as input.2"IN"
tinStringOptionalTaxpayer 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"
address_typeStringOptionalAddress type of the pickup address. Must be either OFFICE or RESIDENTIAL10"OFFICE"
location_codeStringConditional MandatoryIf the location master is active, then only send the location code of the pickup location as per LM."Bhiwandi_wh_1"
vendor_codeStringOptionalPickup vendor code that needs to be sent to the carrier.

Drop Info (drop_info)

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

Field NameData TypeField TypeDescriptionMax LengthExample
latFloatOptionalLatitude of the drop location45.12211
longFloatOptionalLongitude of the drop location88.12342
nameStringMandatoryContact name of the consignee of the shipment100"Mukesh Kumar"
organisationStringMandatoryName of the organisation100"Walmart"
addressStringMandatoryAddress of the drop location500"123, ABC Street"
districtStringOptionalDistrict of the drop location100"Mumbai City"
cityStringMandatoryCity of the drop location100"Mumbai"
stateStringMandatoryState/province of the drop location100"Maharashtra"
landmarkStringOptionalLandmarks to help find the drop location500"Near XYZ Towers"
emailStringMandatoryEmail of the drop contact50"[email protected]"
phoneStringMandatoryContact number of the drop contact11"9876543210"
pincodeStringMandatory6-digit Pin code of the drop location6"400065"
countryStringMandatoryAlpha ISO-2 country code of the drop location. Only "IN" is accepted as input.2"IN"
address_typeStringOptionalAddress type of the drop address. Must be either OFFICE or RESIDENTIAL10"OFFICE"
location_codeStringConditional MandatoryIf the location master is active, then only send the location code of the drop location as per LM"WH-0123"
vendor_codeStringOptionalHub code of the drop address (if the drop address is a warehouse)50"test_drop_warehouse"

Shipment Info (shipment_info)

In the 'shipment_info' object, the details regarding all boxes, and important order details like payment type, order type, courier partner, etc. are added.

Field NameData TypeField TypeDescriptionMax LengthExample
reference_numberStringMandatory

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"
courier_partnerIntegerMandatoryPartner ID of the desired carrier. Refer to List of carriers supported by Clickpost to get the partner ID.123
account_codeStringMandatoryCourier 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'
box_infoListMandatoryDetails of all the boxes present in the shipment
weightIntegerOptionalWeight of the complete shipment (gm)500
cod_valueFloatConditional MandatoryCash to be given to the courier. Must be non-zero for COD orders, and zero for PREPAID orders.25.25
order_idStringOptionalIdentification string for the order100"TestOrderID00001"
order_typeStringMandatoryType of payment of the shipment. Can only take values "COD" or "PREPAID". cod_value must be non-zero for COD shipments and zero for PREPAID shipments.10"COD"/"PREPAID"
delivery_typeStringMandatoryType of delivery to be done. Can only take values "FORWARD" or "RVP".10"FORWARD"/"RVP"
invoice_infoListMandatoryContains details of all the invoices linked to the shipment. You can provide details of multiple Invoice Numbers per shipment.
purchase_order_infoListOptionalContains details of all the purchase orders linked to the shipment. You can provide details of multiple Purchase Orders per shipment.
asn_infoListOptionalContains ASN number and date of the ASN linked to the shipment.
gst_infoObjectMandatoryTax details like GSTIN, tax rate etc
products_in_shipmentArray of objectsOptionalIf you do not have the product details at box level you can use this array to pass product details at shipment level. Please refer product details section to see individual field details. This data is not stored in our db, its only used for sending to some carriers.

Invoice Info(invoice_info)

This is a mandatory sub object inside the shipment_info object. You can provide details of multiple invoices present in the shipment and please provide details of atleast 1 invoice.

Field NameData TypeField TypeDescriptionMax LengthExample
numberStringMandatoryUnique Id number of the invoice
valueFloatMandatoryValue of the shipment as mentioned in the invoice.
dateDateMandatoryDate of issuance of the invoice of the shipment. (YYYY-MM-DD format only)
base64StringOptionalA Base64 string representation of the invoice document file
ewaybill_serial_numberStringConditional OptionalEwaybill serial number of the invoice. It is needed when the invoice value is >=Rs 50K. Some carriers like VRL Logistics, SR Cargo, Xpressbees Cargo require this as a mandatory field so OC will fail without this.
ewaybill_expiry_dateDateOptionalExpiry date of the Ewaybill
descriptionStringOptionalInvoice description, can be used to provide details about the invoice like quantity contained in the invoice

Purchase Order Info (purchase_order_info)

This is an optional sub object inside the shipment_info object. You can provide details of multiple purchase orders present in the shipment and please provide details of atleast 1 purchase order.

Field NameData TypeField TypeDescriptionMax LengthExample
numberStringOptionalPurchase order number
expiry_dateStringOptionalDate of expiry of the purchase order

Box Info (box_info)

This is a mandatory sub object inside the shipment_info object. In the 'box_info' object, provide the details related to a box like length, breadth, height, weight, product info etc.

🚧

Note: Each box object represents a carton box and should have the following:

Field NameData TypeField TypeDescriptionMax LengthExample
reference_number_prefixStringOptionalUnique Id of the box. If there are multiple identical boxes then mention the prefix of the reference no. System will add .001, .002 to the prefix to distinguish each box of that type.Ref001
countIntegerMandatoryNo. of identical boxes of a type. If each box has different attributes (like L,B, H, W, invoice, po , product etc) then keep count as 1.3
codeStringConditional OptionalIf box master is enabled then use the enter the box code in this field.
If box master is not enabled then leave this field empty.
Small_Box_1
heightIntegerMandatoryHeight of the box in cm
lengthIntegerMandatoryLength of the box in cm
breadthIntegerMandatoryBreadth of the box in cm
weightIntegerMandatoryDry weight of the box in gm
descriptionStringOptionalDescription of the box
purchase_order_infoListOptionalMention PO number which is linked to this box. PO Number mentioned here should be present at shipment level
invoice_infoListOptionalMention invoice number which is linked to this box. Invoice Number mentioned here should be present at shipment level
product_infoListOptionalDetails of the product contained in the box

Product Info (product_info)

Each box can have multiple products. For each product provide the details in the product_info object. This object is optional.

Field NameData TypeField TypeDescriptionMax LengthExample
skuStringOptionalSKU Code of the productSKU-3467
sku_countIntegerOptionalNo of products belonging to this SKU code12
descriptionStringOptionalDescription of the productRed shoes
product_categoryStringOptionalProduct categoryFootwear
manufacturer_countryStringOptionalIndia
manufacturer_country_codeStringOptionalIN
hsn_codeStringOptionalHSN001
priceFloatOptionalPrice of each sku unit500

GST Info

This is a mandatory sub object inside the shipment_info object. In the 'gst_info' object, provide the details related to tax.

Field NameData TypeField TypeDescriptionMax LengthExample
enterprise_gstinStringMandatoryGST No of enterprise shipping the shipment100
seller_gstinStringOptionalGST No of seller sending the shipment (will be different from above for marketplaces)100
taxable_valueFloatOptionalTaxable amount for GST (in INR)
place_of_supplyStringOptionalPlace of supply of the service or product. Please refer to https://cleartax.in/s/gst-state-code-jurisdiction
for further details
100
gst_discountFloatOptionalDiscount under GST, if any
gst_total_taxFloatOptionalTotal GST applicable for the shipment (in INR)
sgst_tax_rateFloatOptionalTax percent applicable for SGST for the shipment
sgst_amountFloatOptionalSGST Amount levied on the shipment (in INR)
igst_amountFloatOptionalTax percent applicable for IGST for the shipment
igst_tax_rateFloatOptionalIGST Amount levied on the shipment (in INR)
cgst_tax_rateFloatOptionalTax percent applicable for CGST for the shipment
cgst_amountFloatOptionalCGST Amount levied on the shipment (in INR)
consignee_gstinStringMandatoryGST No of consignee

Appointment Info

This is an optional object inside the shipment_info object. If you do appointment based deliveries in qcommerce and ecommerce marketplaces then you can provide appointment details here and the same can be communicated to carriers over mail.

Field NameData TypeField TypeDescriptionMax LengthExample
idStringOptionalAppointment Id as received from the destination centre
start_timeDatetimeOptionalAppointment Start Time in IST
Format- YYYY-MM-DDTHH:MM:SS+0530
2025-03-04T10:00:00+0530
end_timeDatetimeOptionalAppointment End Time in IST
Format- YYYY-MM-DDTHH:MM:SS+0530
2025-03-04T14:00:00+0530

Additional Info

In the "additional" object optional fields can be passed which may be used by the courier partner, or give additional details for the order, e.g. Async/Sync order creation or whether label generation is needed.

Field NameData TypeFieldDescriptionMax LengthExample
is_label_requiredBooleanOptionalWhether label is required for the order or not. Defaults to true.
is_box_sticker_requiredBooleanOptionalIf you need box stickers then pass true. Default value is true.
is_asyncBooleanOptionalIf you want synchronous flow then pass false. Default value is true.
zoneStringOptionalZone of the location of pickup100"XYZ Locality"
is_multi_sellerBooleanOptional
  • Required for multi-seller shipments only*. Denotes whether the shipment has multiple items, each with different GST numbers. Defaults to false
return_infoObjectOptionalDetails for the return address in case the delivery of the order fails or the order is returned.
order_dateStringOptional

Date when the order was placed for this shipment. To be provided in YYYY-MM-DD format only

Can also be sent in the DateTime format i.e. YYYY-MM-DDTHH:MM:SS

50"2022-12-15" or "2023-09-20T14:00:00"
user_defined_field_arrayListOptional

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 4 objects.

[ {  
"name":"udf_1",  
"type":"String",  
"value":""  
}, {  
"name":"udf_2",  
"type":"String",  
"value":""  
}]
🚧

If you want box stickers and label then go with asynchronous flow. Keep is_async field as true and is_box_sticker_required field also as true.

Return Info

In the optional return_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. If the return info is not sent explicitly, then by default the system considers pickup info as return info.

Field NameData TypeField TypeDescriptionMax LengthExample
latFloatOptionalLatitude of the return location45.12211
longFloatOptionalLongitude of the return location88.12342
nameStringOptionalContact name of the consignor of the shipment100"Mukesh Kumar"
organisationStringOptionalName of the organisation100"Walmart"
addressStringOptionalAddress of the return location500"123, ABC Street"
districtStringOptionalDistrict of the return location100"Nadia"
cityStringOptionalCity of the return location100"Mumbai City"
stateStringOptionalState/province of the return location100"Maharashtra"
landmarkStringOptionalLandmarks to help find the return location500"Near XYZ Towers"
emailStringOptionalEmail of the return contact50"[email protected]"
phoneStringOptionalContact number of the return contact11"9876543210"
pincodeStringOptional6-digit Pin code of the return location6"400065"
countryStringOptionalAlpha ISO-2 country code of the return location. Only "IN" is accepted as input.2"IN"
tinStringOptionalTaxpayer 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"
address_typeStringOptionalAddress type of the pickup address. Must be either OFFICE or RESIDENTIAL10"OFFICE"
location_codeStringConditional MandatoryIf the location master is active, then only send the location code of the pickup location as per LM."Bhiwandi_wh_1"
vendor_codeStringOptionalPickup vendor code that needs to be sent to the carrier.

Polling the API

This API works in async mode. This means that initially you will only get an acknowledgement that the response has been received. You will have to poll the API using the GET function frequently to check if the order was created successfully or not. To poll the API there are two methods-

Method 1: (Recommended) Using GET function with query params without payload

In this method pass the following query params

Field NameData TypeFieldDescriptionMax LengthExample
usernameStringMandatoryUsername of the enterprise100"test-enterprise"
keyStringMandatoryUnique license key provided by Clickpost for the enterprise (This string is a UUID)100"582a839a-d02c-42d8-a731"
reference_numberStringMandatory

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"
courier_partnerStringMandatoryPartner ID of the desired carrier. Refer to List of carriers supported by Clickpost to get the partner ID.123
account_codeStringMandatoryCourier 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.100test_courier'
curl --location 'https://www.clickpost.in/api/v1/create-b2b-order/?username=test-enterprise&key=a28be92&reference_number=TEST-28012024-0002&courier_partner=129&account_code=1'\
--header 'Content-Type: application/json'

Method 2: Using GET function with complete payload

In this method, use the exact same payload and endpoint as the POST function just change the function from POST to GET

curl --location --request GET 'https://www.clickpost.in/api/v1/create-b2b-order/?username=test-enterpirse&key=80dc-fd31da28be92' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pickup_info": {
        "name": "CL-FC-CHN-PGR-Packing",
        "phone": "9999999999",
        "district": "test_district",
        "city": "Chennai",
        "landmark": "test_landmark",
        "organisation": "test_organisation",
        "state": "TamilNadu",
        "time": "2022-10-27T11:52:36",
        "pincode": "600034",
        "country": "India",
        "address_type": "",
        "address": "NEW NO.150 OLD NO.60,RAMA Naiken STREET, Nungambakkam",
        "email": "[email protected]",
        "vendor_code": "",
        "location_code": "",
        "tin": "test"
    },
    "drop_info": {
       
        "organisation": "test_organisation",
        "district": "test_drop_district",
        "address_type": "",
        "vendor_code": "",
        "name": "CL-ST-PUD-PuducherryKamaraj ",
        "landmark": "test_landamrk",
        "phone": "99999999",
        "email": "[email protected]",
        "city": "Puducherry",
        "state": "Puducherry",
        "pincode": "110002",
        "country": "India",
        "location_code": "",
        "address": "104, Kamaraj Salai, "
    },
    "shipment_info": {
        "description": "test",
        "reference_number": "TEST-anmol89078213",
        "courier_partner": "129",
        "account_code": "1",
        "cod_value": 0,
        "order_type": "PREPAID",
        "order_id": "TESTorder_id1",
        "delivery_type": "FORWARD",
        "weight": 3000,
        "invoice_info": [
            {
                "number": "inv-1",
                "value": 10000,
                "date": "2024-09-30",
                "base64": "",
                "ewaybill_serial_number": "E234",
                "ewaybill_expiry_date": "2024-12-30"
            },
            {
                "number": "inv-2",
                "value": 10000,
                "date": "2024-09-30",
                "base64": "",
                "ewaybill_serial_number": "E123",
                "ewaybill_expiry_date": "2024-12-30"
            }
        ],
        "purchase_order_info": [
            {
                "number": "po-1",
                "expiry_date": "2024-09-30"
            },
            {
                "number": "po-2",
                "expiry_date": "2024-09-30"
            }
        ],
        "asn_info": [
            {
                "asn_number": "asn-1",
                "asn_date": "2024-09-30"
            }
        ],
        "box_info": [
            {
                "count": 1,
                "reference_number_prefix": "",
                "height": 20,
                "length": 10,
                "weight": 10,
                "breadth": 30,
                "description": "test description",
                "purchase_order_info": [
                    {
                        "number": "po-1"
                    }
                ],
                "invoice_info": [
                    {
                        "number": "inv-2"
                    }
                ],
                "product_info": [
                    {
                        "sku": "test_sku",
                        "sku_count": "2",
                        "description": "test description",
                        "product_category": "",
                        "manufacturer_country": "",
                        "manufacturer_country_code": "",
                        "hsn_code": "",
                        "price": 10000
                    },
                    {
                        "sku": "test_sku",
                        "sku_count": "2",
                        "description": "test description",
                        "product_category": "",
                        "manufacturer_country": "",
                        "manufacturer_country_code": "",
                        "hsn_code": "",
                        "price": 10000
                    }
                ]
            },
            {
                "count": 5,
                "reference_number_prefix": "",
                "height": 10,
                "length": 10,
                "weight": 10,
                "breadth": 10,
                "description": "test description2",
                "purchase_order_info": [
                    {
                        "number": "po-1"
                    },
                    {
                        "number": "po-2"
                    }
                ],
                "invoice_info": [
                   
                    {
                        "number": "inv-2"
                    }
                ],
                "product_info": [
                    {
                        "sku": "test_sku",
                        "sku_count": "2",
                        "description": "test description",
                        "product_category": "",
                        "manufacturer_country": "",
                        "manufacturer_country_code": "",
                        "hsn_code": "",
                        "price": 10000
                    },
                    {
                        "sku": "test_sku",
                        "sku_count": "2",
                        "description": "test description",
                        "product_category": "",
                        "manufacturer_country": "",
                        "manufacturer_country_code": "",
                        "hsn_code": "",
                        "price": 10000
                    }
                ]
            }
        ],
        "gst_info": {
            "seller_gstin": "",
            "enterprise_gstin": "",
            "taxable_value": 0,
            "is_seller_registered_under_gst": null,
            "place_of_supply": "",
            "gst_discount": 0,
            "gst_total_tax": 0,
            "sgst_tax_rate": 0,
            "sgst_amount": 0,
            "igst_tax_rate": 0,
            "igst_amount": 0,
            "cgst_tax_rate": 0,
            "cgst_amount": 0,
            "consignee_gstin": "",
            "sgst_total_tax": 0
        }
    },
    "appointment_info": {
        "start_time": "2025-05-24T10:00:00+0530",
        "end_time": "2025-05-24T12:00:00+0530",
        "id": ""
    },
    "additional_info": {
        "return_info": {
            "lat": 20.45,
            "long": 40.54,
            "name": "CL-FC-CHN-PGR-Packing",
            "phone": "99999999",
            "district": "test_district",
            "city": "Chennai",
            "landmark": "test_landmark",
            "organisation": "test_organisation",
            "state": "TamilNadu",
            "time": "2022-10-27T11:52:36",
            "pincode": "600034",
            "country": "India",
            "address_type": "",
            "address": "NEW NO.150 OLD NO.60,RAMA Naiken STREET, Nungambakkam",
            "email": "[email protected]",
            "vendor_code": "",
            "location_code": "",
            "tin": "test"
        },
        "is_label_required": true,
       "is_box_sticker_required": true,
        "is_multi_seller": false,
        "is_async": true,
        "zone": "",
        "order_date": "2024-10-11",
        "store_code": "Delhi004",
        "user_defined_field_array": [
            {
                "name": "udf_1",
                "type": "String",
                "value": ""
            }
        ]
    }
}'

Validations

  1. If an invoice or PO number is present at the box level then the details of this invoice and PO must be declared at the shipment level.
  2. However, if any shipment-level invoice is not linked to any box, it is not an issue. We will consume it as-is without linking it to any box.
  3. Location master is supported for 2 combinations- Only Pickup and Pickup +Drop.
  4. If location master is enabled then you can send either the location code or leave the location code empty and send the data in other fields mentioned below. Do not send both location code and data in these fields in the same request.
    • lat
    • long
    • name
    • organization
    • address
    • district
    • city
    • state
    • landmark
    • email
    • phone
    • pincode
    • country
    • address_type
  5. If box master is enabled the box length, breadth and height fields should be left empty. If these fields are not empty then you will receive an error.
  6. If you are sending box reference number prefix in any of the box objects then you need to send it in all the box objects. Either send it in all box objects or dont send it at all.
  7. Box reference number prefix has to be unique for each box object.

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/courier.

Field NameData TypeDescription
metaObjectMetadata for the request, e.g. status code, error messages.
resultObjectActual result of the request
tracking_idIntegerA special ID of the request used for tracking

Response Meta

Field NameData TypeDescription
statusIntegerStatus code for the request (including but not limited to HTTP Status codes)
messageStringError/Success messages for the request
successBooleanWhether the order was successfully created or not
reference_numberStringReference number of the shipment

Response Result

Field NameData TypeDescription
waybillStringWaybill of the newly created order. This waybill is automatically registered for tracking in our database
reference_numberStringReference number of the order, sent in the payload.
labelString/NullURL to the generated waybill copy of the order. If labels are not needed, this stays null.
box_stickersStringURL to the generated box stickers of the shipment. Box stickers are available in 2 sizes by default- A6 and A8.
child_waybillListList of child waybill numbers when number of boxes greater than 1
courier_partner_idIntegerID of the courier partner
courier_nameStringName of the courier
security_keyStringUUID security key of the order that needs to be stored at the enterprise's end.
account_codeStringAccount code of the courier account as per ClickPost system.

Sample Response

Since, this API is async, you will first get a 102 response acknowledging that we have the received the request to create an order. You need to poll the API using a GET function. If the order creation is successful then you will get a 200 response.

{
    "meta": {
        "status": 102,
        "message": "We are processing your order",
        "success": true,
        "username": "acme-test",
        "reference_number": "TEST-gati-16",
        "b2b_shipment_id": 3302
    },
    "result": {
        "pickup_info": {
            "email": "[email protected]",
            "time": "2022-10-27T11:52:36",
            "name": "2030 PacificDehradun",
            "phone": "9999999999",
            "address": "Unit No LG 05 Lower Ground Floor  Jakhan Rajpur Road Opp  Scholars Home School  Dehradun",
            "tin": "05AABCF0689C1ZZ",
            "state": "UTTARAKHAND",
            "pincode": "248006",
            "country": "India",
            "city": "UTTARAKHAND",
            "lat": null,
            "long": null,
            "district": null,
            "landmark": null,
            "organisation": "Acme Inc",
            "address_type": null,
            "vendor_code": null,
            "location_code": "2030"
        },
        "drop_info": {
            "name": "CL-ST-PUD-PuducherryKamaraj",
            "phone": "999999999",
            "city": "Puducherry",
            "state": "Puducherry",
            "pincode": "110002",
            "country": "India",
            "address": "104, Kamaraj Salai,",
            "email": "[email protected]",
            "tin": null,
            "lat": null,
            "long": null,
            "district": "test_drop_district",
            "landmark": "test_landamrk",
            "organisation": "test_organisation",
            "address_type": null,
            "vendor_code": null,
            "location_code": null
        },
        "shipment_info": {
            "order_type": "PREPAID",
            "delivery_type": "FORWARD",
            "order_id": "TESTorder_id1",
            "cod_value": 0.0,
            "courier_partner": 71,
            "account_code": "Gati",
            "reference_number": "TEST-gati-16",
            "weight": 3000.0,
            "invoice_info": [
                {
                    "number": "inv-1",
                    "value": 10000.0,
                    "date": "2024-09-30",
                    "base64": null,
                    "description": null,
                    "ewaybill_serial_number": "E234",
                    "ewaybill_expiry_date": "2024-12-30"
                },
                {
                    "number": "inv-2",
                    "value": 10000.0,
                    "date": "2024-09-30",
                    "base64": null,
                    "description": null,
                    "ewaybill_serial_number": "E123",
                    "ewaybill_expiry_date": "2024-12-30"
                }
            ],
            "purchase_order_info": [
                {
                    "number": null,
                    "expiry_date": null
                }
            ],
            "asn_info": [
                {
                    "number": null,
                    "date": null
                }
            ],
            "gst_info": {
                "seller_gstin": null,
                "enterprise_gstin": "05AABCF0689C1ZZ",
                "taxable_value": 0.0,
                "is_seller_registered_under_gst": null,
                "place_of_supply": null,
                "gst_discount": 0.0,
                "gst_total_tax": 0.0,
                "sgst_tax_rate": 0.0,
                "sgst_amount": 0.0,
                "igst_tax_rate": 0.0,
                "igst_amount": 0.0,
                "cgst_tax_rate": 0.0,
                "cgst_amount": 0.0,
                "consignee_gstin": null
            },
            "box_info": [
                {
                    "count": 1,
                    "reference_number_prefix": null,
                    "height": 20.0,
                    "length": 10.0,
                    "weight": 10.0,
                    "breadth": 30.0,
                    "description": "test description",
                    "invoice_info": [
                        {
                            "number": null,
                            "value": null,
                            "date": null,
                            "base64": null,
                            "description": null,
                            "ewaybill_serial_number": null,
                            "ewaybill_expiry_date": null
                        }
                    ],
                    "purchase_order_info": [
                        {
                            "number": null,
                            "expiry_date": null
                        }
                    ],
                    "product_info": [
                        {
                            "sku": null,
                            "sku_count": null,
                            "price": null,
                            "description": null,
                            "product_category": null,
                            "manufacturer_country": null,
                            "manufacturer_country_code": null,
                            "hsn_code": null
                        }
                    ]
                },
                {
                    "count": 5,
                    "reference_number_prefix": null,
                    "height": 10.0,
                    "length": 10.0,
                    "weight": 10.0,
                    "breadth": 10.0,
                    "description": "test description2",
                    "invoice_info": [
                        {
                            "number": null,
                            "value": null,
                            "date": null,
                            "base64": null,
                            "description": null,
                            "ewaybill_serial_number": null,
                            "ewaybill_expiry_date": null
                        }
                    ],
                    "purchase_order_info": [
                        {
                            "number": null,
                            "expiry_date": null
                        }
                    ],
                    "product_info": [
                        {
                            "sku": null,
                            "sku_count": null,
                            "price": null,
                            "description": null,
                            "product_category": null,
                            "manufacturer_country": null,
                            "manufacturer_country_code": null,
                            "hsn_code": null
                        }
                    ]
                }
            ],
            "description": "test"
        },
        "additional_info": {
            "return_info": {
                "name": "2030 PacificDehradun",
                "phone": "999999999",
                "city": "UTTARAKHAND",
                "state": "UTTARAKHAND",
                "pincode": "248006",
                "country": "India",
                "address": "Unit No LG 05 Lower Ground Floor  Jakhan Rajpur Road Opp  Scholars Home School  Dehradun",
                "email": "[email protected]",
                "lat": null,
                "long": null,
                "district": null,
                "landmark": null
            },
            "is_label_required": true,
            "source": "API",
            "is_multi_seller": false,
            "zone": null,
            "order_date": null,
            "store_code": null,
            "b2b_file_upload_info_id": null,
            "b2b_file_upload_shipment_info_id": null
        },
        "appointment_info": {
            "start_time": null,
            "end_time": null,
            "id": null
        }
    }
}
{
    "meta": {
        "status": 200,
        "success": true,
        "message": "Order Placed Successfully",
        "reference_number": "TEST-om-123123124"
    },
    "tracking_id": 1453644353,
    "result": {
        "label": "https://pyck-res-bucket.s3.amazonaws.com:443/GATIB2B/2025-03-12/52.pdf",
        "box_stickers": {
            "A6": "https://clickpost-label-mumbai.s3.amazonaws.com:443/forevernew-test/2025-03-12/174179.pdf",
            "A8": "https://clickpost-label-mumbai.s3.amazonaws.com:443/forevernew-test/2025-03-12/17418.pdf"
        },
        "waybill": "52826",
        "child_waybill": [
            "90803",
            "908804",
            "9088705",
            "903906",
            "908877",
            "90808"
        ],
        "reference_number": "TEST-om-123123124",
        "security_key": "4ba78ad3-62f6-4a24-b98f-ec122f",
        "courier_name": "Gati B2B MPS",
        "courier_partner_id": 71,
        "account_code": "Gati"
    }
{
    "meta": {
        "status": 200,
        "success": true,
        "message": "Order Placed Successfully",
        "reference_number": "SHADOWFAX-TEST-1010102"
    },
    "tracking_id": 1453580682,
    "result": {
        "label": null,
        "box_stickers": null,
        "waybill": "SFLR011312",
        "child_waybill": [
            "SFLR0",
            "SFP2191",
            "SFP2192",
            "SFP2194"
        ],
        "reference_number": "SHADOWFAX-TEST-1010102",
        "courier_name": "SHADOWFAX_MPS",
        "courier_partner_id": 501,
        "pickup_request_number": null,
        "account_code": "test_new_b2b"
    }
}
{
    "meta": {
        "status": 420,
        "message": "Order Creation Failed",
        "success": false,
        "username": "forevernew-test",
        "reference_number": "TEST-gati-16"
    },
    "result": {
        "shipment_info": {
            "account_code": [
                "This field is required."
            ]
        }
    }
}

Error Codes

If you are calling the API in Async mode then please refer this sheet for error codes.


Did this page help you?