Dash101 Direct Integration (1.0)

Welcome to Dash101's API documentation.
Dash101 Platform provides options for integration with external systems. Dash101 provides APIs which can be used to manage order lifecycle. This document aims to provide all of the information needed for developers to use Dash101 resources.

Getting Started

First, need to register with Dash101 and create an account. Click on the link to register.
After registration is done, follow the below steps to create an API user and integrate Dash101's services into your platform

1. Login into Dash101 Portal and on the left-hand panel, click on "API Integration".



2. Click on the "Create New API User" button. Then on the pop-up menu, fill in an email and enter the appropriate password and confirm the password.



3. On Successful completion, the API user would be created.



API User is characterized by API User Id, Email, and Password. All three attributes would be required in 'Generating Authentication Token' and an authentication token is required to use all further APIs provided by Dash101.

Note:

  • Once the password is reset for the API user, all previously generated authorization tokens would be invalidated.
  • After marking an API user inactive, all API calls for the user would be temporarily blocked.

Document and API usage guidelines

  • order_id in APIs request and response would refer to order id provided by you whereas, dash101_order_id would refer to Dash101's order id
  • We may be adding extra fields in the response of certain APIs as we build, so implementation should be done in such a way that integration doesn't fail in addition of fields in response.

Errors and Response Codes

Following standard response and error codes could be encountered, while using Dash101's API.

Code Description
200 and 201 API call is successful.
400 Bad Request.
401 Unauthorized request.
404 The requested resource is not found.
422 Unprocessable Entity.
429 Too many requests have been made in a short period of time (Throttling).
500 The server could not return the representation due to an internal server error.

Order Status Codes and Order Status

Following table contains order status codes and corresponding status

Order Status Code Order Status
1 Created
2 Approved
2.5 Pending Pickup
3 Dispatched
4 Delivered
5 Cancelled
6 Cancelled by Buyer
7 Returned to Origin
9 Return Request Initiated
10 Return Item picked up
11 Out for Delivery
12 Failed Delivery
13 Returning to Origin
14 Return Request Approved
15 Return Request Completed

Authorization

  • The authorization token is required to use all protected APIs of Dash101. Use this API to validate your API user and generate an authorization token.
  • The authorization token is valid for 20 days from the time of generation. So you need to re-generate the token once it expires.
  • Make sure, not to share the authorization token in publicly accessible areas.
  • The authorization token needs to be passed in the header of all API calls in the format Authorization:Bearer {{Token Value}}

Generate authentication token

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

header Parameters
Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
email
required
string

API User's email

password
required
string

API User's password

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "authorization_token": "..."
}

Courier Partners

You can check the serviceability between pickup and drop pincodes along with the prices and details of courier partners in real-time.

Check pincode serviceability and get shipping price

This API should be used to check if the pickup and drop pincode combination is serviceable by any of Dash101's courier partners. If serviceability is possible, the shipping related charges would be returned in the response.

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

query Parameters
pickup_pincode
required
number
Example: pickup_pincode=110092

Pickup Pincode

drop_pincode
required
number
Example: drop_pincode=400708

Drop Pincode

cod
required
boolean
Example: cod=true

Whether order is COD(Cash on Delivery) or Prepaid. If this flag is set to false, order would be considered as Prepaid.

weight
required
number
Example: weight=1.5

Weight of the package(in Kg). Minimum value should be 0.5kg and Maximum value can be 10Kg.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"

Responses

Response samples

Content type
application/json
{
  • "available_courier_companies": [
    ]
}

Get all courier partners available

This API should be used to get all the courier partners available to create a shipment.

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"

Responses

Response samples

Content type
application/json
{
  • "available_courier_companies": [
    ]
}

Orders

Dash101 provides APIs to manage the flow of order creation. You can create, cancel in bulk or track the status of an order.

Create an order V1

This API should be used to create an Order on Dash101's platform. All the required parameters should be passed for a successful call.

Note:

  • Once order is created against your platform's order_id, it should be not repeated again to create another order. Such request would be rejected, even if previously created order is cancelled.

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
order_id
required
string [ 1 .. 20 ] characters

Your Platform's Order Id. Allowed characters are A-Z, a-z, 0-9, "#" and "-"

order_date
string

Timestamp of order creation. The format should be yyyy-MM-dd HH:mm:ss. Timezone is IST.

customer_name
required
string

Customer's name. Non-English characters are not allowed.

customer_phone
required
number [ 10 .. 11 ] characters

Customer's contact number. Should be valid 10 digit mobile number or 11 digit landline number.

customer_email
string

Customer's Email

delivery_address1
required
string <= 100 characters

Customer's Address Line 1. Non-English characters are not allowed.

delivery_address2
string <= 100 characters

Customer's Address Line 2. Non-English characters are not allowed.

delivery_city
required
string <= 50 characters

Delivery City. Non-English characters are not allowed.

delivery_pincode
required
integer [ 6 .. 6 ]

Delivery pincode

order_total
required
number <float>

Total Order Value. Allowed to have max two decimal places.

payment_method
required
string
Enum: "cod" "prepaid"

Type of order, whether COD(Cash on Delivery) or Prepaid.

required
Array of objects [ 1 .. 50 ] items

Details of Order Items

Responses

Request samples

Content type
application/json
{
  • "order_id": "1234567",
  • "order_date": "2021-02-12 12:30:10",
  • "customer_name": "string",
  • "customer_phone": 0,
  • "customer_email": "string",
  • "delivery_address1": "string",
  • "delivery_address2": "string",
  • "delivery_city": "string",
  • "delivery_pincode": 6,
  • "order_total": "101.50",
  • "payment_method": "cod",
  • "order_items": [
    ]
}

Response samples

Content type
application/json
{
  • "dash101_order_id": "2345675432",
  • "order_status": "Created",
  • "order_status_code": "1"
}

Create an order V2

This API should be used to create an Order on Dash101's platform. All the required parameters should be passed for a successful call.

Note:

  • Once order is created against your platform's order_id, if the order_id is repeated again, the current order present in the system will be returned.

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
order_id
required
string [ 1 .. 20 ] characters

Your Platform's Order Id. Allowed characters are A-Z, a-z, 0-9, "#" and "-"

order_date
string

Timestamp of order creation. The format should be yyyy-MM-dd HH:mm:ss. Timezone is IST.

customer_name
required
string

Customer's name. Non-English characters are not allowed.

customer_phone
required
number [ 10 .. 11 ] characters

Customer's contact number. Should be valid 10 digit mobile number or 11 digit landline number.

customer_email
string

Customer's Email

delivery_address1
required
string <= 100 characters

Customer's Address Line 1. Non-English characters are not allowed.

delivery_address2
string <= 100 characters

Customer's Address Line 2. Non-English characters are not allowed.

delivery_city
required
string <= 50 characters

Delivery City. Non-English characters are not allowed.

delivery_pincode
required
integer [ 6 .. 6 ]

Delivery pincode

order_total
required
number <float>

Total Order Value. Allowed to have max two decimal places.

payment_method
required
string
Enum: "cod" "prepaid"

Type of order, whether COD(Cash on Delivery) or Prepaid.

required
Array of objects [ 1 .. 50 ] items

Details of Order Items

Responses

Request samples

Content type
application/json
{
  • "order_id": "1234567",
  • "order_date": "2021-02-12 12:30:10",
  • "customer_name": "string",
  • "customer_phone": 0,
  • "customer_email": "string",
  • "delivery_address1": "string",
  • "delivery_address2": "string",
  • "delivery_city": "string",
  • "delivery_pincode": 6,
  • "order_total": "101.50",
  • "payment_method": "cod",
  • "order_items": [
    ]
}

Response samples

Content type
application/json
{
  • "dash101_order_id": "2345675432",
  • "order_status": "Created",
  • "order_status_code": "1",
  • "message": "Order already present"
}

Batch cancel orders

This API should be used to cancel orders in bulk. Max 10 orders are allowed be cancelled in one request. Both your platform's order id(against key order_id) and Dash101's order id(against key dash101_order_id) can be passed in the cancellation request.

Note:

  • Duplicate order_id or duplicate dash101_order_id should not be passed. Such a request would be rejected.
  • On successful processing of the request, the orders which were cancelled and also those which couldn't be cancelled(along with reason) would be returned back in response.

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
One of
required
Array of objects [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
Example
{
  • "order_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "uncancelled_order_ids": [
    ],
  • "uncancelled_dash101_order_ids": [
    ],
  • "cancelled_order_ids": [
    ],
  • "cancelled_dash101_order_ids": [
    ]
}

Track an order

This API should be used to track an order. Either order_id or dash101_order_id needs be passed to fetch order details.

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

query Parameters
dash101_order_id
any

If details of order needs to fetched through Dash101's order id, then it needs to passed against this parameter.

order_id
any

If details of order needs to fetched through Your platform's order id, then it needs to passed against this parameter.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"

Responses

Response samples

Content type
application/json
{
  • "order_details": {
    }
}

Pickup Locations

Dash101 provides APIs to create and get pickup locations. You can create a pickup location and use it for creating a shipment

Create a pickup location

This API should be used to create a pickup location to be used for pickup while creating a shipment

Notes:

  • Same Pickup Location ID will be returned if all parameters specified are exactly the same
  • Combined length of pickup_address1, pickup_address2, pickup_landmark and pickup_city should not exceed 255 characters

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
pickup_seller_name
required
string [ 1 .. 100 ] characters

Full name of the seller. Non English characters are not allowed

pickup_seller_phone
required
string

Customer's contact number. Should be valid 10 digit mobile number.

pickup_address1
required
string [ 10 .. 100 ] characters

Flat number and building name of the pickup address. Non English characters are not allowed.

pickup_address2
required
string [ 1 .. 100 ] characters

Road and locality of the pickup address. Non English characters are not allowed.

pickup_landmark
string

Pickup address landmark, if any. Non English characters are not allowed

pickup_city
required
string <= 50 characters

Pickup address city. Non English characters are not allowed

pickup_pincode
required
string 6 characters

Pickup address pincode. Should be a valid pincode.

Responses

Request samples

Content type
application/json
{
  • "pickup_seller_name": "El Nino",
  • "pickup_seller_phone": "8421019501",
  • "pickup_address1": "1 XYZ Apartments",
  • "pickup_address2": "ABC Road KMN Nagar",
  • "pickup_landmark": "Famous Stall",
  • "pickup_city": "Mumbai",
  • "pickup_pincode": "400080"
}

Response samples

Content type
application/json
{
  • "pickup_location_id": "8921105879"
}

Get all pickup locations available

This API should be used to get all the pickup locations available to create a shipment.

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"

Responses

Response samples

Content type
application/json
{
  • "available_pickup_locations": [
    ]
}

Shipments

Shipment APIs provide functionality to manage shipments against an order which is created. You can create a shipment against a valid order.

Create a shipment

Once a pickup location is successfully created, you can use this API to ship an order created via direct integration. Either order_id or dash101_order_id needs to be passed to create a shipment against it.

Notes:

  • It will only be possible to ship an order via API if all the suborders are in the Approved state. In any other case, the order will have to be shipped from the Dash101 Seller Panel.
  • The shipment will always be created in 'Pending Pickup' state

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
order_id
string [ 1 .. 20 ] characters

Your Platform's Order Id to create a shipment against it. Allowed characters are A-Z, a-z, 0-9, "#" and "-". If dash101_order_id has been provided then this has to be blank.

dash101_order_id
string

Dash 101 Order Id to create shipment against it. If order_id has been provided then this has to be blank.

courier_partner_id
required
string

The courier partner id through which order has to be shipped.

dead_weight
required
string

The dead weight (in kgs) of the shipment to be created. Minimum value 0.1 and maximum value 10.

length
required
string

The length (in cms) of the shipment to be created. Minimum value 0.5

breadth
required
string

The breadth (in cms) of the shipment to be created. Minimum value 0.5

height
required
string

The height (in cms) of the shipment to be created. Minimum value 0.5

pickup_location_id
required
string

The pickup location id for the shipment to be created.

Responses

Request samples

Content type
application/json
{
  • "order_id": "1234567",
  • "dash101_order_id": "8421019501",
  • "courier_partner_id": "4",
  • "dead_weight": "4.3",
  • "length": "1.2",
  • "breadth": "5.2",
  • "height": "2.6",
  • "pickup_location_id": "8501501010"
}

Response samples

Content type
application/json
{
  • "tracking_number": "8921105019012940",
  • "courier_partner_id": "4",
  • "courier_partner_name": "Delhivery",
  • "tracking_url": "https://xyz",
  • "scheduled_pickup_date": "2020-2-2",
  • "scheduled_pickup_timeslot": "13:00-18:00",
  • "pickup_request_number": "2409124021",
  • "routing_code": "PUN/HJD/",
  • "shipping_label": "https://shipping_label",
  • "order_details_file": "https://order_details",
  • "order_status": "Pending Pickup",
  • "order_status_code": "2.5",
  • "shipping_charges": "13.23",
  • "cod_charges": "1.3",
  • "shipping_tax_invoice": "https://Tax_Invoice"
}

Reattempt delivery

This API should be used to re-attempt delivery for a shipment in the failed delivery state.

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

trackingNumber
required
string

Tracking number of shipment.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
preferred_delivery_date
string

The date on which the seller wants the delivery of the shipment to be reattempted. Format would be yyyy-MM-dd If registering response before 4PM , minimum date should be tomorrow's date , else minimum date should day after day after tomorrow's date

updated_customer_address
string

The updated address of the customer (should only include flat number, building name, road, locality, landmark; should NOT include city, state or pincode). Original address will be considered if this is empty. Should be at least 10 characters long.

alternate_customer_mobile
string

Alternate mobile number of the customer on which the delivery agent could call the customer for delivery.

Responses

Request samples

Content type
application/json
{
  • "preferred_delivery_date": "2020-02-12",
  • "updated_customer_address": "ABC DEF GHIJ LMNO",
  • "alternate_customer_mobile": "9999999990"
}

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "message": "success"
}

RTO a shipment

This API should be used to give an RTO (Return to Origin) instruction on a shipment in the failed delivery state

path Parameters
apiUserId
required
integer <int64>

Pass API User Id, created from Dash101's API Integration section.

trackingNumber
required
string

Tracking number of shipment.

header Parameters
Authorization
required
string
Example: Authorization:Bearer <token value>

Authorization Token

Content-Type
required
string
Value: "application/json"
Request Body schema: application/json
rto_reason
required
string
Enum: 1 2 3 4 5 6


Reason for RTO. Should be a value between 1 and 6 (both inclusive)

RTO Reason Value RTO Reason Description
1 Delivery is taking too long
2 Customer is out of station
3 Delivery person not reachable
4 Fake Scan by delivery person
5 Rude behaviour by delivery person
6 Other

rto_comments
string

Any additional comments the seller wishes to provide. Maximum 255 characters

Responses

Request samples

Content type
application/json
{
  • "rto_reason": "1",
  • "rto_comments": "Customer MIA"
}

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "message": "success"
}