Creating the Import Map

Note:  We have provided a test file for you.  It is attached to the end of this help article.  It is the same file used in this tutorial.  So, if you do not have an order file currently but still wish to learn the process, please feel free to download the attached Excel file and use it to learn the mapping process.


ShipWorks currently has integrations to more than 80 online marketplaces and sales channels. However, in some case it may be necessary to import orders from a source other than one of our integrations.  For example, you may sell on a sales channel or store that ShipWorks is not directly integrated with, but you can export your order information from your sales channel into an Excel spreadsheet, CSV file, or a text file.

The good news is that ShipWorks allows you to easily grab data from your external file so that you can import the order information into the ShipWorks software.  You then have all the ShipWorks tools available to you to easily and quickly ship your orders.

In this article, we will take a look at how to connect ShipWorks to your email account and how to have ShipWorks import your orders from an email attachment.

Please Note:

If you will be importing from a local directory on your PC or Network, click here for instructions.

If you will be importing your orders from an FTP directory, click here for instructions.

First Things First

There are a couple of things that you will need to have in place prior to beginning the process of mapping your file to the ShipWorks software:

1.  You will need the file that you wish to import into ShipWorks.  The file will need to include at least one order.

Q:  What are the requirements for the file?

A:  Great question!  ShipWorks can import from an Excel spreadsheet (.xls or .xlsx file), a .csv (comma delimited) or text file, or from an XML file.  There is no set format or structure the file needs to be in because we will be defining what data is pulled from the file and to which fields in ShipWorks the data gets imported into. However, the file does need to have column headings.

  • The file needs to be an Excel spreadsheet, a .csv file, a text (delimited) file, or an XML file.
  • The file needs to have valid column headings.
  • The Order Number field is required.
  • The Order Number field can be numeric or alpha-numeric.

Here is a quick example of what an Excel file might look like. Note the valid column headings.


2.  In addition to having your file available to you, you will need to have an email account available to which you have administrative rights.  You will also need:

The email login username

The email login password

In addition, you may need:

The email account's IMAP settings


The Email account's POP settings

The Email account's SMTP settings

If you do not have this information, please reach out to your resident IT person or network administrator.

The Process

Mapping your file to ShipWorks can be broken down into the following steps:

1.  Selecting the type of file to import

2.  Connecting ShipWorks to the email account.

3.  Pointing ShipWorks to the folder or directory.

4.  Selecting the import file you will use to create your mapping.

5.  Mapping the fields in your file to the fields in ShipWorks.

6.  Importing your orders.

Selecting the File Type

Let's get started!  

1.  If you have not done so, launch the ShipWorks application.

2.  Inside of ShipWorks, click on the Manage tab and then click on the Stores button.


3.  On the Manage Stores screen, click on the Add Store button.


4.  From the What platform do you sell on? menu, select Generic File.  Then, click Next.


5.  Now, select the type of file you will be importing from the What type of file will ShipWorks be importing: option.  Then, click Next.

For this example, we are importing from an Excel spreadsheet, so we have selected the Excel option.


6.  Next, we need to tell ShipWorks from where we are pulling our order data.  From the Import the data from: menu select Incoming email.


Connecting Your Email Account to ShipWorks

1.  On the Import the data from: screen, click on the Setup button to the right of the Email Account: field.


2.  The Account Setup screen allows you to attempt to connect to your email account by using automatic settings or to connect by manually entering all of the information about your email account. For this example, we will use the Automatic Configuration option.

Note: For more detailed information on how to configure an email account with ShipWorks, please refer to the article on how to add your email account to ShipWorks.

2a.  Verify that Automatic Configuration is selected.


2b.  Fill in the information for the following fields.

Your Name:  The name associated to the email account.  

Email Address:  The email address to which you are attempting to connect.

Password:  The password for the email account to which you are attempting to connect.


2c.  Click Next.  ShipWorks will contact the email server and attempt to automatically configure the settings needed to connect.


2d.  Once Shipworks connects to the email account successfully, you will be prompted to enter an account alias.  The alias is just how you see the name for this email account in ShipWorks.  It is not included in any emails sent.

Enter an alias and then click Next.


2e.  On the Setup Complete screen, click Finish.

PLEASE NOTE: If you are unsuccessful in adding your email account using the automatic configuration option you can attempt to connect using the Manual Configuration option. For more information, please refer to the article on how to add your email account to ShipWorks.  

Selecting the Incoming Mail Folder

Great!  Now that your email account is setup with ShipWorks you need to specify from which email folder you would like ShipWorks to import the order files from.

1.  On the Import Data From screen, click on the Browse button to the right of the Mail Folder: field.


2.  A list showing the available folders associated to your email account will be listed.  Select the folder from which the emails containing your ShipWorks orders will be imported from.  Then, click OK.

Note:  In this example, we are going to configure ShipWorks to pull the order files directly from the inbox folder.  However, if you have set up a specific folder from which ShipWorks orders will be imported, please select this folder.


Specifying Which Messages Contain Your Order Files

ShipWorks allows you to specify which messages have the ShipWorks order files attached to them.  This allows you to tell ShipWorks to only import those email messages and to ignore any other email messages that may be in the folder that you selected.

For this example we will specify the following:

  • To only import new email messages.
  • To only import from email messages that have a subject line of ShipWorks Import.

1.  On the Import the Data From: screen, check the box for Only import unread messages.


2.  Now, check the box for Only import mail with subjects that match: and then enter the subject line for emails containing your ShipWorks Orders.  For this example we will use ShipWorks Import.


3.  If you wish, you can also specify for ShipWorks to ignore any emails that contain a particular subject line.


After a Successful Import

Now, let's tell ShipWorks to move the email message to a specific email folder after the orders are successfully imported into ShipWorks.  For this example, we have an email folder named Completed Imports.  We will tell ShipWorks to move the email message to this email folder so that we have a record of the files imported into ShipWorks in the event we should need to refer back to them.

1.  Verify that Move the Message is selected under After a successful import.


Note:  You do have the option of having the file deleted after a successful import.

2.  Click the Browse button to the right of the Folder: field.  Then, select to email folder to which you would like ShipWorks t move the email message after a successful import. Click OK.


When an Error Occurs?

There are two options that you can select from for when an error occurs while importing an import file.  Let's take a look at them:

  • Stop importing and display the error - When an error occurs, ShipWorks will not move the file, but instead will stop importing and pop up a message to help you determine the cause of the error.
  • Move the file and continue importing - ShipWorks will not stop importing the file and will move the file to the Complete folder once finished.  However, this may cause orders to be missed in ShipWorks since it skips the order or data that caused the error.

9.  From the If an error occurs while importing: drop-down menu, select the option that works best for you.  In this example, we are leaving the default to stop and display an error.  Then, click Next.


Nice job!  We are now ready to select the actual import file and to begin the mapping process.

Creating the Import Map

Now, we are going to point ShipWorks to the actual order file that we wish to use for mapping.  

1.  In the Import Map screen, click on the New Map button.


2.  OK, now we have to navigate to and select a copy of the import file.  So, click on Browse, navigate to your local copy of the import file you will use to create your mapping.  Then, click Open.

PLEASE NOTE: You will need to have a copy of your order file available to you saved locally on your ShipWorks PC.  You will not be pointing to an email for mapping purposes.  Instead, you will use a local copy of your order file.




3.  After selecting the import file, ShipWorks will display the data found in the file so that you can be sure that it looks correct.  By default, ShipWorks will look to the first row of an Excel file (row A) for the column headers.  However, you can modify this if your headers are located on a row other than the first row of your spreadsheet or data source.  Once the data is correct, click Next.




Mapping the Fields in the Import File to Fields in ShipWorks

If you have never mapped a file to an application or database before, it is super easy.  What we will be doing is defining to ShipWorks exactly where ShipWorks should import your data to.  For example, ShipWorks does not know that it should place the customer's first name into the First Name field.  So, we are going to tell ShipWorks where to place our data.

NOTE:  The only field that is required in ShipWorks to be mapped is the Order Number field.  All other fields are optional.  So, if you only have a few fields in your import file, this is totally OK.  You can map only the fields that you need to.

Before we begin mapping, take a look at the Map Setting  section.  it gives you the File Name, source information and Date format information.  If the Date format is not correct, you can click on the Edit button to manually configure the date and time settings.


OK, let's begin mapping.

Notice that ShipWorks breaks the data down into 3 separate groups, Orders, Address, and Items.  When you select one of the three groups, only the fields in ShipWorks that relate to this group are made available for mapping.  This is done to help organize the mapping process.


In addition, the Column Mapping screen is divided into two columns.  The ShipWorks Field column lists the available fields in the ShipWorks database while the Source Column allows you to select from your import file what data should be imported into the ShipWorks Field.


We will not go through mapping every single field in our file.  That would make this article really, really long.  So, instead we will map two or three columns for each group so that you can see how it is done.

1.  Select Orders from the Column Mappings screen.  Now, let's map the Order Number.  In the Source Column click the drop-down menu to the right of Order Number.  A list of all of the available columns in your source file will be displayed along with examples of the data from your import file.


2a.  Click on the Column Name that houses your order number data.  Notice that the OrderNumber source column is now mapped to the Order Number field in ShipWorks.  This means that when you import your orders, ShipWorks knows where to place the order number in its' database.


2b.  Let's map one more column from the Orders group.  Sometimes, you will need to map to a field in ShipWorks based upon how your input file is formatted. For example, you will notice that ShipWorks has an Order Date and Time field AND separate Order Date and Order Time fields. Our sample import file only has an order date so we will only use the Order Date field. However, if you have both the order date and the order time in the same column, you may wish to use the Order Date and Time field in ShipWorks.


2c.  Continue mapping all of the Order fields in your import file to the fields available to you in ShipWorks.

3.  Select the Address group on the  Column Mappings screen.  Notice that the ShipWorks Fields change to show only the fields that relate to address information.


Note:  ShipWorks allows you to import both Ship to and Bill to address information.  Neither are required.  You can import one or the other or both.

3a.  In our sample import file, we only have one address.  So, we will map our address columns to the Ship to fields in ShipWorks.  Map your address columns to the available fields in ShipWorks.

Mapping the Ship First Name field



Mapping the Ship Last Name field


Mapping the Ship to Address1 field.


3.  Continue mapping the address columns from your import file to the available fields in ShipWorks.

4.  Select the Items group from the Column Mappings section.  The screen changes to display only the ShipWorks fields related to items.


5. Make note of the Multiple Items section available to you now.  You will use this section to define how the line items are listed in your import file.  There are two options available to you. Let's take a look at both of these options.

  • All items are on the same line as the order - If all of the items are listed on the same row as the order information in your input file, then this is the option for you.  Here is an example:


With this option selected, you can select the max number of items you will need to map to ShipWorks and how many attributes are available for each item.


  • The order line is repeated for each item - If your import file has a separate row for each line item on the order, this option is for you.  Here is an example:  Notice that the OrderNumber is repeated on each row indicating that the items belong to the same order.


With this option selected you can specify what column of your input file identifies each order and the number of attributes associated to your items.


5a.  Based upon the above examples, select the correct option for your import file.  For this example, we will select the below options:



5b.  Map the appropriate columns from your import file to the correct fields in ShipWorks.



6.  When you have completed mapping all of your Order, Address, and Item fields, click Next.


Congratulations!  You have completed the Generic File setup!

7.  Click Finish.  Then, click Close.

Test Your Mapping

Once you have completed your Generic File setup you will be able to import the orders from your order file attached to an unread email .  To test your setup:

1.  Ensure that an email has been sent to the email account you connected to in the above steps being sure that the email contains an attachment of the order file you wish to import.  For our example we have an email with the subject of ShipWorks Import which contains our attached order file.  There is also an email in our inbox with a subject line of Do Not Import.  This is so that we can ensure ShipWorks will only grab the emails we wish for it to per our settings above.


2.  In ShipWorks, go to the Home tab and then click on the Download button.


If all goes well you will see your orders being imported into the ShipWorks software.


You will also notice that the import file was moved from the email Inbox folder into the Completed Imports email folder we created in the steps above. 



Still Need Help?

Hopefully you were successful and your orders imported into ShipWorks without any issues. However, if you did run into an issue we are here to help.  Please feel free to reach out to one of our awesome Customer Care Representatives in St. Louis.