Shipment Orders

These set of APIs will help you create, manipulate, delete shipment orders as well as get the order details.

Fetch an Order details

GET /orders/shipment/{orderId}

This API is used to get the order and the shipment details of a particular order by passing the orderId in the endpoint URL. Type the orderId in place of {orderId}. Note: The orderId is sent to the customer when an order is created.

Path Parameters

Name	Type	Description
orderId*	string	Reference number passed when order is created

Headers

Name	Type	Description
API_KEY*	string	API key obtained by the Customer/Partner

200 Detailed data of the shipment

{
    "status": "PASS",
    "message": {
        "order_details": {
            "order_id": 4892552,
            "reference_number": "000000005-2-7",
            "awb_number": "SH-22T70ZX",
            "status": "Complete",
            "delivery_hub_sn": "Taj MG Road Bengaluru",
            "delivery_address": "MyCornerBakery, Hosa Road, Golden Hill Square, Bangalore, 560068, Karnataka, India",
            "delivery_postal_code": "560068",
            "pickup_address": "Taj MG Road, Bengaluru, Mahatma Gandhi Road, Yellappa Garden, Yellappa Chetty Layout, Sivanchetti Gardens, Bengaluru, Karnataka, India",
            "pickup_postal_code": "560001",
            "customer_name": "John Doe",
            "customer_mobile": 9876543210,
            "alternate_customer_mobile": null,
            "pickup_customer_name": "",
            "pickup_customer_mobile": null,
            "item_details": {
                "2714539": {
                    "item_name": "Fusion Backpack",
                    "item_quantity": 1,
                    "item_qty_picked": 1,
                    "item_qty_delivered": 1
                }
            },
            "cash_on_delivery": "59.00"
        }
    }
}

400 Malformed data or missing required parameter values

{
  "status": "string",
  "message": "string"
}

401 Unauthorized / Wrong api key

{
  "status": "FAIL",
  "message": "Unauthorized"
}

500 Unauthorized/Validation Error

{
  "status": "FAIL",
  "message": "Unexpected error"}

Create a new order

POST /orders/shipment

Use this API to create an order in the Blowhorn's system. Pass all the required params at the minimum to create an order and optional params as per the preference. The delivery hub, pickup hub is optional as it is automatically deduced from the delivery address pin code unless the customer wants it to be specifically routed via the hub.

Kitting is a process where in KIT (package of SKUs) is created and sellers can define a preconfigured set as displayed in Example Value 2. For e.g. Take a choc box Celebrations box of 25 as a KIT SKU which can have 5 dairy milk, 20 5 star chocolates another configuration could be 15 diary milk, 5 snickers, 5 5 star chocolates and so on.

Headers

Name	Type	Description
API_KEY*	string	API key obtained by the Customer/Partner

Request Body

Name	Type	Description
awb_number	String	AWB bill number is a confirmation for the shipment(s) in the order lines to be delivered. No need to set it if labelling is done at Blowhorn end. The "create new order" API will pass back a SH-XXXXXX awb number.
reference_number*	String	A unique reference number like the order id / shipment tracking reference number. For every reference_number we will send out an AWB number as its unique tracking number. The same number can be reused if the order is cancelled for other orders.
is_hyperlocal	String	The customers will have to pass it as true for the order to be considered under the Hyperlocal contract. If the parameter is not passed, it will take up the shipment contract (if the same exists).
delivery_hub	String	The hub from which the deliveries will be made. This is set using the serviceability API for the coverage / pincode by the hub. This is automatically deduced from the delivery address pin code, unless the customer wants it to be specifically routed via the hub.
pickup_hub	String	The hub from which the stock will be picked up for delivery. This is set using the serviceability API for the coverage / pincode by the hub. This is automatically deduced from the pickup address pin code unless the customer wants it to be specifically routed via the hub.
customer_name	String	Name of the end consumer / recipient of the shipment being delivered.
customer_mobile*	String	Phone number of the end consumer / recipient of the shipment
alternate_customer_mobile	String	An alternate number to reach the recipient in case the primary contact number is not reachable
customer_email	String	The email address to send tracking link or any delivery related communication.
customer_reference_number	String	Any other reference number that the brand is using to identify the shipment.
delivery_postal_code	String	The pincode of the delivery address where the shipment is expected to be delivered.
delivery_lat	String	The latitude and longitude of the delivery address. Although optional, it helps our delivery partners to identify the location of customers without any additional help.
delivery_long	String	The latitude and longitude of the delivery address. Although optional, it helps our delivery partners to identify the location of customers without any additional help.
delivery_address*	String	The address where the shipment is expected to be delivered.
pickup_address	String	The address where the shipment is expected to be picked up from.
pickup_postal_code	String	The pincode of the pickup address.
pickup_lat	String	The latitude and longitude of the delivery address. Although optional, it helps our delivery partners to identify the location of customers without any additional help.
pickup_long	String	The latitude and longitude of the delivery address. Although optional, it helps our delivery partners to identify the location of customers without any additional help.
is_return_order	String	Whether this order needs to be picked back from the customer. Default value is 'false'
commercial_class	String	Is there a request for a specific vehicle class?
is_commercial_address	String	Helps us to plan the deliveries based on timings. Default value is 'false'
priority	String	In case of multiple deliveries we intend to use the expected delivery time to specifically focus the priority in which orders are delivered. Use this field to specifically add priority to the orders.
pickup_datetime	String	The time at which the shipment is to be picked up. Applicable only in cases of orders which involve pickup and return orders.
expected_delivery_time	String	Very important field to determine by when the delivery is expected to happen. This will be used in prioritising shipments.
division	String	The division of the city for easy distinguishing for delivering the shipment.
is_cod	String	Set to 'true' if the mode of payment is Cash on delivery. Default value is 'false'
cash_on_delivery	String	The amount in INR to be collected by Blowhorn on behalf of the customer if it is COD.
item_details	String	The line items or details of the orders in terms of SKUs and quantity.
item_name*	String	The quantity of the SKU that should be fulfilled
item_price_per_each	String	Selling price of the SKU
total_item_price	String	The sell price of the entire line taking into account the discounts(invoice value).
item_category	String	Product Group of SKUs
brand	String	The supplier / vendor of the SKU
weight	String	The weight of the items in kilograms (KGs)
volume	String	The volume of the item in cc
length, breadth, height	String	the dimensions of the package (in centimeters)
what3words	String	A unique combination of three words for every 3 sq. meter area by what3words
packages_count	int	packages_count > Number of packages/boxes the order is split into. if not sent or this is 0 or 1 then entire order line items assumed to be in single package. Note: If package_count sent then package_id should not be sent else will lead to rejection of the order.
package_id	String	package_id >a unique identifier for package where this order line items is packed into. considering all unique package_ids form order line items, number of packages will be derived for tracking and delivery purposes. Note: If package_id sent then package_count should not be sent else will lead to rejection of the order.

200 On successful creation of an order

{
  "status": "PASS",
  "message": {
    "awb_number": "SH-GHT6RTW",
    "item_details": {
      "9325": {
        "item_name": "Wall Fit",
        "item_quantity": 6,
        "item_price_per_each": 80,
        "total_item_price": 480
      },
      "9326": {
        "item_name": "Wires",
        "item_quantity": 4,
        "item_price_per_each": 130,
        "total_item_price": 520
      }
    },
    "child_awb_numbers": []
  }
}

401 Unauthorised / Wrong api key

{
  "status": "FAIL",
  "message": "Unauthorized"
}

500 Unexpected error

{
  "status": "FAIL",
  "message": "Unexpected error"
}

400: Bad Request Existing reference number in the system

{
    "status": "FAIL",
    "message": "Shipment Reference Number is required"
}

Example Value | Schema(Request Body)

{
  "awb_number": "ORDER0001",
  "delivery_hub": "Bellandur [ BH Micro warehouse ]",
  "pickup_hub": "Koramangala [ BH Micro warehouse ]",
  "is_hyperlocal": "false",
  "customer_name": "Mahadevappa",
  "customer_mobile": "9434343434",
  "pin_number": "1234123",
  "alternate_customer_mobile": "8913452678",
  "customer_email": "[e-mail]",
  "delivery_address": "413, 2nd cross, 17th C main, 5th Block, koramangala, Bengaluru",
  "delivery_postal_code": "560095",
  "what3words":"circling.novelists.wades",
  "reference_number": "517082419558167201",
  "customer_reference_number": "TEST0013",
  "delivery_lat": "12.9538477",
  "delivery_lon": "77.3507366",
  "pickup_address": "b-205, Nagarjuna Green Ridge, 19th Main, Sector 2, HSR Layout, Bengaluru",
  "pickup_postal_code": "560102",
  "pickup_lat": "12.9238437",
  "pickup_lon": "77.3509366",
  "pickup_customer_name": "Ambaraya",
  "pickup_customer_mobile": "9753434343",
  "is_return_order": false,
  "commercial_class": "Two Wheeler",
  "priority": "2",
  "weight": "10",
  "volume": "1000",
  "length": "10",
  "breadth": "10",
  "height": "10",
  "is_commercial_address": true,
  "pickup_datetime": "2018-12-07T19:35:06.959084",
  "division": "Bengaluru South",
  "expected_delivery_time": "2018-12-07T19:35:06.959084",
  "is_cod": true,
  "cash_on_delivery": "123456",
  "packages_count": 2
  "item_details": [
    {
      "item_name": "Wall Fit",
      "item_quantity": 6,
      "item_price_per_each": 80,
      "total_item_price": 480,
      "item_category": "Fittings",
      "brand": "WFit",
      "weight": "10",
      "volume": "1000",
      "cgst": "9.0",
      "sgst": "9.0",
      "igst": "100.0"
    },
    {
      "item_name": "Wires",
      "item_quantity": 4,
      "item_price_per_each": 130,
      "total_item_price": 520,
      "item_category": "Hardware",
      "brand": "Finolex",
      "weight": "5",
      "volume": "200"
    }
  ]
}

Example Value 2 | Schema(Kitting SKUs)

{
  "customer_name": "Jitendra",
  "customer_mobile": "9776076661",
  "delivery_address": "Amrutahalli mail  road ,Amritahalli, Bengaluru",
  "delivery_postal_code": "560092",
  "what3words":"circling.novelists.wades",
  "reference_number": "383a146a6a0",
  "customer_reference_number": "252aa1a05",
  "pickup_hub": "1058",
  "pickup_address": "New Airport Road Chikkajala BANGALORE Karnataka 562157",
  "pickup_postal_code": "562157",
  "expected_delivery_time": "2021-11-13T16:47:06.959084",
  "is_cod": false,
  "cash_on_delivery": null,
  "is_return_order": true,
  "commercial_class": null,
  "is_commercial_address": false,
  "division": null,
  "carrier_mode": "Blowhorn Heavy",
  "packages_count": 2
  "kit_skus": [
      {
          "name": "test",
          "description": "TEST",
          "item_details": [{
            "item_name": "Sports Goods",
            "item_quantity": 1,
            "item_price_per_each": 749,
            "total_item_price": 749,
            "brand": "Decathlon",
            "weight": "1",
            "length": "0",
            "breadth": "0",
            "height": "0",
            "package_id": "Box-1"
          }]
      },
      {
          "name": "akshara",
          "description": "NNNN",
          "item_details": [{
            "item_name": "Sports Goods",
            "item_quantity": 1,
            "item_price_per_each": 500,
            "total_item_price": 480,
            "item_category": "Fittings",
            "brand": "Decathlon",
            "weight": "1",
            "volume": "0",
            "package_id": "Box-2"
           }]
       }
   ]
}

Update an Order

PUT /orders/shipment/{orderId}

Use this API to update the shipment order already created with Blowhorn by using the same orderId which was received while creating an order with the "Create new order" Api. Type the received orderId in place of {orderId}. Note: The orderId is sent to the customer when an order is created.

Headers

Name	Type	Description
API_KEY*	string	API key obtained by the Customer/Partner

Request Body

Name	Type	Description
delivery_hub	String	The hub from which the deliveries will be made. This is set using the serviceability API for the coverage / pincode by the hub. This is automatically deduced from the delivery address pin code, unless the customer wants it to be specifically routed via the hub.
pickup_hub	String	The hub from which the stock will be picked up for delivery. This is set using the serviceability API for the coverage / pincode by the hub. This is automatically deduced from the pickup address pin code unless the customer wants it to be specifically routed via the hub.
customer_name	String	Name of the end consumer / recipient of the shipment being delivered.
customer_mobile*	String	Phone number of the end consumer / recipient of the shipment
alternate_customer_mobile	String	An alternate number to reach the recipient in case the primary contact number is not reachable
customer_email	String	The email address to send tracking link or any delivery related communication.
delivery_postal_code	String	The pincode of the delivery address where the shipment is expected to be delivered.
delivery_lat	String	The latitude and longitude of the delivery address. Although optional, it helps our delivery partners to identify the location of customers without any additional help.
delivery_long	String	The latitude and longitude of the delivery address. Although optional, it helps our delivery partners to identify the location of customers without any additional help.
delivery_address*	String	The address where the shipment is expected to be delivered.
pickup_address	String	The address where the shipment is expected to be picked up from.
pickup_postal_code	String	The pincode of the pickup address.
pickup_lat	String	The latitude and longitude of the delivery address. Although optional, it helps our delivery partners to identify the location of customers without any additional help.
pickup_long	String	The latitude and longitude of the delivery address. Although optional, it helps our delivery partners to identify the location of customers without any additional help.
commercial_class	String	Is there a request for a specific vehicle class?
is_commercial_address	String	Helps us to plan the deliveries based on timings. Default value is 'false'
priority	String	In case of multiple deliveries we intend to use the expected delivery time to specifically focus the priority in which orders are delivered. Use this field to specifically add priority to the orders.
pickup_datetime	String	The time at which the shipment is to be picked up. Applicable only in cases of orders which involve pickup and return orders.
expected_delivery_time	String	Very important field to determine by when the delivery is expected to happen. This will be used in prioritising shipments.
division	String	The division of the city for easy distinguishing for delivering the shipment.
is_cod	String	Set to 'true' if the mode of payment is Cash on delivery. Default value is 'false'
cash_on_delivery	String	The amount in INR to be collected by Blowhorn on behalf of the customer if it is COD.
item_details	String	The line items or details of the orders in terms of SKUs and quantity.
item_name*	String	The quantity of the SKU that should be fulfilled
item_price_per_each	String	Selling price of the SKU
total_item_price	String	The sell price of the entire line taking into account the discounts(invoice value).
item_category	String	Product Group of SKUs
brand	String	The supplier / vendor of the SKU

200 On successful updation of an order

{
  "status": "PASS",
  "message": {
    "awb_number": "SH-GHT6RTW",
    "item_details": {
      "9325": {
        "item_name": "Wall Fit",
        "item_quantity": 6,
        "item_price_per_each": 80,
        "total_item_price": 480
      },
      "9326": {
        "item_name": "Wires",
        "item_quantity": 4,
        "item_price_per_each": 130,
        "total_item_price": 520
      }
    }
  }
}

401 Unauthorised / Wrong api key

{
  "status": "FAIL",
  "message": "Unauthorized"
}

500 Unexpected error

{
  "status": "FAIL",
  "message": "Unexpected error}

400: Bad Request Existing reference number in the system

{
    "status": "FAIL",
    "message": "Shipment Reference Number is required"
}

Example Value | Schema

{
  "customer_name": "Mahadev",
  "customer_mobile": "9434343500",
  "customer_email": "[e-mail]",
  "delivery_address": "413, 2nd cross, 17th C main, 5th Block, koramangala, Bengaluru",
  "delivery_postal_code": "560095",
  "delivery_lat": "12.9538477",
  "delivery_lon": "77.3507366",
  "pickup_address": "b-205, Nagarjuna Green Ridge, 19th Main, Sector 2, HSR Layout, Bengaluru",
  "pickup_postal_code": "560102",
  "pickup_lat": "12.9238437",
  "pickup_lon": "77.3509366",
  "is_cod": true,
  "cash_on_delivery": "123456",
  "item_details": {
    "9325": {
      "item_name": "Wall Fit",
      "item_quantity": 60,
      "item_price_per_each": 80,
      "total_item_price": 480
    },
    "9326": {
      "item_name": "Wires",
      "item_quantity": 40,
      "item_price_per_each": 130,
      "total_item_price": 520
    }
  }
}

Add items to an Order

PUT /orders/add/items/{orderId}

Use this API to add items to an already created order using the orderId received while creating the order using the "Create new order" Api. Type the received orderId in place of {orderId}. Note: The orderId is sent to the customer when an order is created.

Headers

Name	Type	Description
API_KEY*	string	API key obtained by the Customer/Partner

Request Body

Name	Type	Description
item_details	String	The line items or details of the orders in terms of SKUs and quantity.
item_name*	String	The quantity of the SKU that should be fulfilled
item_price_per_each	String	Selling price of the SKU
total_item_price	String	The sell price of the entire line taking into account the discounts(invoice value).
item_category	String	Product Group of SKUs
brand	String	The supplier / vendor of the SKU
weight	String	The weight of the items in grams
volume	String	The volume of the items in cc

200 On successful updation of an order

{
  "status": "PASS",
  "message": {
    "awb_number": "SH-GHT6RTW",
    "item_details": {
      "9325": {
        "item_name": "Wall Fit",
        "item_quantity": 6,
        "item_price_per_each": 80,
        "total_item_price": 480
      },
      "9326": {
        "item_name": "Wires",
        "item_quantity": 4,
        "item_price_per_each": 130,
        "total_item_price": 520
      }
    }
  }
}

401 Unauthorised / Wrong api key

{
  "status": "FAIL",
  "message": "Unauthorized"
}

500 Unexpected error

{
  "status": "FAIL",
  "message": "Unexpected error}

400: Bad Request Existing reference number in the system

{
    "status": "FAIL",
    "message": "Shipment Reference Number is required"
}

Example Value | Schema

{
    "item_details": {
        "9325": {
            "item_name": "Wall Fit",
            "item_quantity": 60,
            "item_price_per_each": 80,
            "total_item_price": 480,
            "item_category": "Hardware",
            "brand": "Finolex",
            "weight": "5",
            "volume": "200"
        },
        "9326": {
            "item_name": "Wires",
            "item_quantity": 40,
            "item_price_per_each": 130,
            "total_item_price": 520,
            "item_category": "Hardware",
            "brand": "Finolex",
            "weight": "5",
            "volume": "200"
        }
    }
}

Delete items from an Order

PUT /orders/delete/items/{orderId}

Use this API to delete the items of the existing order using the OrderId received while creating the order. Type the OrderId received in place of {orderId}. Note: The orderId is sent to the customer when an order is created.

Path Parameters

Name	Type	Description
orderId*	string	AWB Number / Shipment ID received when order is created

Headers

Name	Type	Description
API_KEY*	string	Contact Blowhorn team for API Key

200 On successful deletion of the items corresponding to the given ids in the item list

{
  "status": "PASS",
  "message": "Items deleted for AWB Number : AILP0000000043"
}

400 Malformed data or missing required parameter values or item_ids doesn't belong to the given order

{
    "status": "FAIL",
    "message": "Missing required parameters."
}

401 Unauthorised / Wrong api key

{
  "status": "FAIL",
  "message": "Unauthorized"
}

500 Unexpected error

{
  "status": "FAIL",
  "message": "Unexpected error"
}

Example Value | Schema

{
  "item_list": [
    "9325",
    "9326"
  ]
}

We have a Postman collection to make the integration quicker and easier. You can test all our APIs by importing the full API collection through the 'Run in Postman' button and running them in the Postman app.