> For the complete documentation index, see [llms.txt](https://doc.blowhorn.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.blowhorn.com/api-docs/orders/shipment-apis.md). # 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 | {% tabs %} {% tab title="200 Detailed data of the shipment" %} ```json { "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, "delivery_hub": "Koramangala [BH Microwarehouse]", "item_details": { "2714539": { "item_name": "Fusion Backpack", "item_quantity": 1, "item_qty_picked": 1, "item_qty_delivered": 1 } }, "return_address": "Distribution Logistics Infrastructure Pvt Ltd Park (ILP) Maranayanakanahalli,Bengaluru, Karnataka,Bengaluru,Karnataka,India", "return_postal_code": "562107", "return_customer_name": "John", "return_customer_mobile": 9434343434, "return_hub": "testcustomer_bengaluru_hub" "cash_on_delivery": "59.00" } } } ``` {% endtab %} {% tab title="400 Malformed data or missing required parameter values" %} ```json { "status": "string", "message": "string" } ``` {% endtab %} {% tab title="401 Unauthorized / Wrong api key" %} ```json { "status": "FAIL", "message": "Unauthorized" } ``` {% endtab %} {% tab title="500 Unauthorized/Validation Error" %} ```json { "status": "FAIL", "message": "Unexpected error"} ``` {% endtab %} {% endtabs %} ## 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).

| | is\_inventory\_managed\_bh | String | This parameter must be set to 'true' for orders to be processed under the WMS system. Default value is 'false' | | 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' | | is\_inventory\_managed\_bh | String | This parameter must be set to 'true' for orders to be processed under the WMS system. 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. | | return\_address | String | The address where the shipment is expected to be returned. | | return\_postal\_code | String | The postal code (PIN code) of the return address | | return\_lat | String | The latitude coordinate of the return address | | return\_lon | String | The latitude coordinate of the return address | | return\_hub | String | The hub or facility where the returned item will be processed or handled. (If hub details are provided, it takes priority over the return address) | {% tabs %} {% tab title="200 On successful creation of an order" %} ```json { "status": "PASS", "message": { "awb_number": "SH-GHT6RTW", "delivery_hub": "Koramangala [BH Microwarehouse]", "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": [] } } ``` {% endtab %} {% tab title="401 Unauthorised / Wrong api key" %} ```json { "status": "FAIL", "message": "Unauthorized" } ``` {% endtab %} {% tab title="500 Unexpected error" %} ```json { "status": "FAIL", "message": "Unexpected error" } ``` {% endtab %} {% tab title="400: Bad Request Existing reference number in the system" %} ```json { "status": "FAIL", "message": "Shipment Reference Number is required" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Example Value | Schema(Request Body)" %} ```javascript { "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": "test@example.com", "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", "return_lat": "12.9538477", "return_lon": "77.3507366", "return_customer_name": "John", "return_customer_mobile": "9434343434", "return_address": "413, 2nd cross, 17th C main, 5th Block, koramangala, Bengaluru", "return_postal_code": "560095", "return_hub":"testcustomer_bengaluru_hub", "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" } ] } ``` {% endtab %} {% tab title="Example Value 2 | Schema(Kitting SKUs)" %} ```json { "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" }] } ] } ``` {% endtab %} {% endtabs %} ## 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 | | return\_address | String | The address where the shipment is expected to be returned. | | return\_postal\_code | String | The postal code (PIN code) of the return address | | return\_lat | String | The latitude coordinate of the return address | | return\_lon | String | The latitude coordinate of the return address | | return\_hub | String | The hub or facility where the returned item will be processed or handled. (If hub details are provided, it takes priority over the return address) | {% tabs %} {% tab title="200 On successful updation of an order" %} ```json { "status": "PASS", "message": { "awb_number": "SH-GHT6RTW", "delivery_hub": "Koramangala [BH Microwarehouse]", "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 } } } } ``` {% endtab %} {% tab title="401 Unauthorised / Wrong api key" %} ```json { "status": "FAIL", "message": "Unauthorized" } ``` {% endtab %} {% tab title="500 Unexpected error" %} ```json { "status": "FAIL", "message": "Unexpected error} ``` {% endtab %} {% tab title="400: Bad Request Existing reference number in the system" %} ```json { "status": "FAIL", "message": "Shipment Reference Number is required" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Example Value | Schema" %} ```javascript { "customer_name": "Mahadev", "customer_mobile": "9434343500", "customer_email": "test@example.com", "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", "return_lat": "12.9538477", "return_lon": "77.3507366", "return_customer_name": "John", "return_customer_mobile": "9434343434", "return_address": "413, 2nd cross, 17th C main, 5th Block, koramangala, Bengaluru", "return_postal_code": "560095", "return_hub":"testcustomer_bengaluru_hub", "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 } } } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200 On successful updation of an order" %} ```json { "status": "PASS", "message": { "awb_number": "SH-GHT6RTW", "delivery_hub": "Koramangala [BH Microwarehouse]", "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 } } } } ``` {% endtab %} {% tab title="401 Unauthorised / Wrong api key" %} ```json { "status": "FAIL", "message": "Unauthorized" } ``` {% endtab %} {% tab title="500 Unexpected error" %} ```json { "status": "FAIL", "message": "Unexpected error} ``` {% endtab %} {% tab title="400: Bad Request Existing reference number in the system" %} ```json { "status": "FAIL", "message": "Shipment Reference Number is required" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Example Value | Schema" %} ```javascript { "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" } } } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200 On successful deletion of the items corresponding to the given ids in the item list" %} ```json { "status": "PASS", "message": "Items deleted for AWB Number : AILP0000000043" } ``` {% endtab %} {% tab title="400 Malformed data or missing required parameter values or item\_ids doesn't belong to the given order" %} ```json { "status": "FAIL", "message": "Missing required parameters." } ``` {% endtab %} {% tab title="401 Unauthorised / Wrong api key" %} ```json { "status": "FAIL", "message": "Unauthorized" } ``` {% endtab %} {% tab title="500 Unexpected error" %} ```json { "status": "FAIL", "message": "Unexpected error" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Example Value | Schema" %} ```javascript { "item_list": [ "9325", "9326" ] } ``` {% endtab %} {% endtabs %} 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. [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/47346810-6d24b30b-2d26-46c1-878a-9479eb45c7af)