Setup default import order mapping on an account

The default order mapping can be setup on an account from the account details without the need of additional coding from the Dispatch Science development team. The .CSV template is attached to this article, see bottom of article.

Open Accounts and in list of Accounts, click on an Account Name to open its details.

In Account Details under Order Options, click on Create Standard Mapping link

You will receive a message, click on OK to create the standard mapping or on Cancel to abort.

Once the mapping has been associated to the account, you will see the confirmation message at the top and the mapping associated to the account.

Enter Orders in Import File

Download the import file. It is very important to keep the column header name as is, they should not be renamed.

Required Columns

The following columns should always be filled in:

Dropoff Contact Name, Address Line 1, City, Province and Postal Code.

Service Level

Ready At

Optional Pickup Columns

If the pickup columns are not in the import file or are left blank, the Account User default contact, if setup will be used to fill in the pickup information. If the Account User does not have a default contact, the Account default contact will be used if the columns are not in the import file or are left blank.
 Pickup Contact Name, Address Line 1, City, Province and Postal Code.

Please note that if no default contact is found on the Account User or Account, an error will be generated for the order.

Reference Fields

The first 3 columns will be used to import values in the Reference fields:

Reference Number 1, Reference Number 2, Reference Number 3
Those fields represent the 3 reference fields that are setup for in the Profile for the account. Do not rename those columns even if they are named differently in the profile. They will map to the first, second and third reference field.

Service Level

The service level should be entered as its ID. You can find this information under Pricing, Service Levels. Open a service level schedule to see the list of Service level IDs.

Ready At and Delivery window

There are 2 different ways to send the Pickup and Delivery time:

Using Ready At and Service Level:

Delete columns Del Date, Del no earlier than, Del no later than (columns D, E, F).

Enter a Ready At date-time (format yyyy-mm-dd hh:mm) and a service level. These will be used to automatically calculate the order's pickup and drop off windows.

Using the a Delivery window

Enter the date of delivery in the Del Date column.

Enter a time in the Del no earlier than to indicate when the delivery can start

Enter a time in the Del no later than to indicate when the delivery should be completed. The time should be equal to or later than the Del no earlier than.

Enter a Ready At that is  NOT EARLIER THAN the Del date and Del no earlier than time

Enter a service level.

The Ready At will be used to calculate the pickup window, the delivery window will be used as entered.

Vehicle Type Id

Vehicle Type Id refers to the ID on the vehicle. You can find this information under Pricing in the Vehicles:

Pickup and Dropoff Wait Times

If a Pickup Wait Time is entered in the column, it will overwrite the contact wait time when a pickup contact is used (see Optional PIckup Column above) and will be used for the pickup load time.

If a Dropoff Wait Time is entered in this column, it will be added to the order delivery unload time.

Pickup and Dropoff Latitude and Longitude

These 4 fields can be left blank or even removed from the import file if they are not used. 

If these are blank or not present in the file, the geolocation of the pickup and dropoff address will be done by Dispatch Science.

If you enter a latitude and longitude, the address will be used to display and the latitude and longitude will be used as the geolocation. 

Number Of Pieces and Weight vs Items

Depending on the level of information needed for items, the fields to use will be different.  

Number Of Pieces and Weight will keep the order items generic, using the default parcel type and no additional information. 

If item information such as description, quantity, barcodes are needed, you will use the fields starting with Item_.

Standard Import File without detailed item information

Number Of Pieces

Enter the number of pieces in the order. A parcel, using the lowest ranked parcel type from the parcel type schedule associated with the account, will be used to create the order. 

If you enter 0 piece, no parcel will be created on the order.
Additional item fields such as Item_Parcel Type Id, Item_Description, etc..,  are not available when using Number Of Pieces and Weight. To use the additional item fields, please use the fields starting with Item_Quantity.


If weight is omitted, it will default to 0. If a weight is entered, it will be split in between each of the parcel as entered in Number of pieces. 

Standard Import File with additional Item information and barcode

This file will be used if you want to enter the items or parcels for each order. 

On the first row of an order, fill in the information for the order and the first parcel.

On the subsequent rows of the order, only fill in the information for the parcels. 

See Filled in Standard with items to be used as an example.csv file at the bottom of this article. 

Item Information


Item_Quantity determines the number for each item row in the import file. Entering a barcode, description, item user field will copy this information to all items created with the Item_Quantity. Item_Weight is the total weight for all items in Item_Quantity and not the individual weight of each item. 

Item_Parcel Type Id

This will be the ID on the parcel type schedule associated to the account.

If this is left blank, the item will not be added to the order.


This will be added in the description field on the parcel


This is the weight of the item. If a minimum weight was entered in the parcel type, the weight will be displayed in the order but the minimum weight will be used for the calculation of the weight extra fee.

Item_Length, Item_Width, Item_Height

These field will contain the length, width and height in the unit of measure associated with the parcel type as entered in Item_Parcel Type Id if the parcel type was set as customizable. If entries are added in those columns and the parcel type is not set to be customizable, the order will not be created and an error will be added in the log file. 

Item_Barcode Template

This will contain the barcode for the item. If there are no barcodes entered, the barcode will be left blank.

If some of the barcodes are entered and others are left blank, the ones that are blank will be blank.

If no barcodes are entered for any of the items in the order and there is a custom barcode template setup on the account, the barcodes will be created upon import. 

Extra Fee Columns

If extra fees should be added to the orders, you can add columns with the following header:

Extra extrafeeID

For instance, if I have an Extra Fee with ID BOLSignature and a description of BOL Signature, the column header will be:

Extra BOLSignature

It is important to leave a space between Extra and the Id of the Extra Fee Id.

In that column, you will enter the quantity for the extra fee and it will be calculated according to the Extra Fee Schedule associated to the Account. 

Note: Since all accounts can have a different Extra Fee Schedules with different extra fees, the columns are not added in the import file. 

User and Item User Fields

You can now add your account user and item user fields to your import file following the below naming convention.

Item User fields: Item_uf itemuserfieldid

As an example, if I have a User Item field with Id ItemCondition and description Item Condition, enter the header of this columns as Item_uf ItemCondition

It is important to leave a space between uf and the item user field ID

User fields:  uf userfieldId

As an example, if I have a User field with Id OrderCondition and description Order Condition, enter the header of this column as uf OrderCondition

It is important to leave a space between uf and the user fiel ID

Note: Since all accounts can have a different Account Profile with different User and Item user fields, the columns are not added in the import file.

Reuse Route For Matching Address

A new column can be added to the file with the following heading: Reuse Route For Matching Address

In this column, you can enter one of 2 possible entries:


When this column is used, the created order which matches a route property (Account and Service Level) will be associated to the container route matching the pickup or delivery address location of an existing order already on the route within a 164 ft (50m) radius. If no order is found on an existing route matching the address, the order will be added to the route it would be placed in according to the route plan zone. 

Note: If using Route Name, the route name will take precedence if a Route Name is indicated in the row.

Import User Name

If the import is for one Account, this field can be left blank.

If you are importing orders for multiple accounts, the field should contain the email address associated to the Account User for the order. 

Attribute Ids

The Attribute Ids column allows the addition of attributes of type Order or Order and Driver to the orders on import. 

If a Driver attribute is added to the column, it will be ignored when importing the orders and an error will be added to the log file. 


In this column, add the attribute Ids separated by a semi-column (;) as such:


Attribute Ids



If the column is omitted or left blank, the default attributes associated to the account will be added to the order. 

If one or more attribute Ids are entered in this column, the attributes in the column will be added to the order and the default attributes associated to the account will not be added to the order.

If only an invalid attribute is added to the column such as incorrect Id or a Driver attribute Id, there will be no attributes added to order. 

Other Columns

The following column should be used for internal order import and removed when sending the standard import file to your account users.

Route Name

The Route Name can be added to this column. If the order's account and service level matches a Route Plan, the order will be added to the Route Container accordingly in the Route specified. If the Route already exists, the order will be place in the existing Route. If the Route does not exist yet, it will be created and placed in the Route. 

See Driver Number to see how to allocate a driver to a new Route.

Driver Number

If the Driver Number is added to this column, the order will be dispatched to the driver if order is an On Demand Order.

If order falls in a new Route not yet created on a Route Container and the driver is specified, the new route will be allocated to the driver. If a route already exists on a Route Container, the driver will not be allocated to the Route. 

Note: If your driver numbers are not unique, this will create an error and the order will not be dispatched.

Driver Pay

The Driver pay can be added in this column and this will set the predefined commission for the order.

Order Price

If a price is indicated in this column, the delivery price will be overwritten on the order.

For convenience, you have different files that can be given to your accounts and the other marked as internal that you can use yourself with the above 3 fields.

Please note there is also a file named Filled in Standard with Items to be used as an example.csv which does not contain the above 3 fields but give an example on how to fill in the file when there are items.

Import orders for an account

Click on Orders and then click on Import then click on Import File.

Click on Choose File and navigate to location of your file, select the file and click Open. File name will show in the field.

Select the Import Type

By Account: When By Account is selected, you will be able to select the account and the user of the account. 

For Multiple Accounts: When selecting For Multiple Accounts, you will need to add in the file the Import User Name which should be the email of the account user for each order. Select the correct mapping from the drop-down field.

Click on Import to start the importing process. 

You will be returned to the list of Import with the status as Requested:

You can refresh the page using the browser refresh or the refresh at the bottom right of the list to see the updated status or you can leave this page and you will receive an email when the import is done. 

Note that an email will also be sent to the support email associated with Dispatch Science and the users.

In the import list, on the right hand side of each row, you have a download menu. When clicking on the download menu, you can either open the Log File or download the original import file.