Import Orders via CSV

How to use a CSV file to import orders into ShipStation in bulk. Includes how to prepare the CSV, a reference of the field mappings and resolutions for common issues.

ShipStation allows you to import orders from a CSV or tab-delimited file into a manual store. This is useful if you keep track of orders in a spreadsheet or export orders from a selling channel with which ShipStationdoes not yet integrate.

The sections below discuss how to prepare your import file, import the file, map the CSV fields to ShipStation's fields, update orders with a CSV, and resolve common issues.

Import Orders by CSV Demo Video

This video demonstrates the CSV order import process.


Prepare Your Import File

Before you can start the import process, you must make sure your import file is prepared correctly. 

  • Best Practice: Use Row 1 of your CSV as your heading columns (for example, Order Number, Customer Name, Address Line 1, City, etc).

    Your CSV headings do not need to match ShipStation’s. You will map them to the corresponding ShipStation fields during the import process.

  • Order numbers are required. You can enter your own numbers or use the auto-numbering feature (see below).

  • All order numbers should be unique, both to other orders in the CSV and orders within your ShipStation manual store.

    If an order number in your CSV matches an existing order in your manual store in ShipStation, ShipStation will update that order to match the data in the CSV.

  • Multi-item orders: ShipStation will combine rows using the same order number into a single order.

    For example, two rows in a CSV with order number SH1001 will result in the single order SH1001 containing the items from each row in the CSV file.

  • Auto-numbering: ShipStation can auto-number your orders if you set the manual store to allow it.

    To enable auto-numbering on a manual store, go to Settings > Selling Channels > Store Setup > Action Menu Actions menu > Edit Marketplace Connection for the store you wish to modify. Check the box to Automatically generate order numbers for manual orders.

    Manual store settings with outline around the "Automatically generate order number" option, which is enabled.

    In your CSV, enter AUTO into the Order Number column for every order you wish to auto-number. Each row in the CSV will then import as a unique order with an auto-assigned order number.

The method used in ShipStation to assign a specific piece of data from a source to its corresponding field in ShipStation. As in "field mapping" for order imports and "service mapping" for import rules.

Import Your Orders

If you opted to create a new field mapping, you will now be prompted to map your fields. Move on to the Field Mapping section below for detailed instructions. For troubleshooting help with Order Imports, see our CSV Import Troubleshooting article.

The method used in ShipStation to assign a specific piece of data from a source to its corresponding field in ShipStation. As in "field mapping" for order imports and "service mapping" for import rules.

Field Mapping

Field Mapping is how you tell ShipStation where your CSV information should appear. Since your column headers likely won't match exactly the field names in ShipStation, you will map them using this process. 

The ShipStation Field column in the field mapping pop-up displays the ShipStation fields you can map to. The Your Column Header column contains drop-down menus where you can choose from the columns in your CSV file.

If you cannot see the column header names in the import mapping screen, it may be because you have special characters in a Saved Mapping Name. If that is the case, you should remove the special characters from the CSV then start the import process again.

Assign the ShipStation fields on the left with the corresponding column headers on the right.

Import Orders pop-up. ShowsShipStation fields on left and CSV Field dropdown menus on right.

The image above is not a complete list of all available columns. Scrolling down in the popup will reveal all columns available!

Auto-Configured Field Mapping

If you name the column headers in your CSV import file to match the ShipStation field names, the field mapping drop-downs will automatically be set. This means you will not need to manually map each column header.

After mapping all the columns in ShipStation to your data, we recommend saving the field mapping for future imports.

Enter a name into the Field mapping name field. Name the field mapping using only alphanumeric characters.

Close-up of Import Orders pop-up. Red box highlights: Field Mapping Name

When you are ready, click Start Import

Once ShipStation has finished the import process, your orders will be visible in the Awaiting Shipment section of your orders screen in the manual store you chose during the import process.

Notes About Field Mapping

  • You can map as many or as few columns as you need, but the Order # field is required by ShipStation.

  • Each CSV column can only be mapped to a single ShipStation field.


Update Manual Orders - CSV

You can also use the above CSV-import process to update orders that already exist in your manual stores. 

ShipStation will update orders in your selected manual store that has matching order numbers in your CSV file and were originally created by a CSV import (this excludes orders created manually or via API).

CSV Import Replaces Existing Data with CSV Data

Be sure your CSV file contains all the information you need for your order records!

The CSV import process will replace the data in ShipStation with the data from the CSV. This means if you have a blank cell in the CSV for a field that currently contains data in ShipStation, the CSV import will overwrite that data with a null value and that data will no longer be available in ShipStation.

For example, if you initially imported order #12345  with the Order #, Name, Address, City, State, Postal Code, and Country fields: 

Order CSV file in Excel with order information filled in, including order number, customer name, and address.

But you then realize you need to add an SKU to the order...

Add the SKU to the SKU column for the order and retain ALL other existing order information, like this:

Order CSV file in Excel with information filled in columns, including order number, customer name, address, and product SKU.

ShipStation will add the SKU information to order #12345 in SShipStation 

Alternately, if you'd like to remove information from an order, simply delete the information from the appropriate columns before you upload the new file, like this: 

Order CSV file in Excel with order information filled in for order number and SKU columns.

In this example, ShipStation will delete the Name, Address, City, State, Postal Code, and Country from order #12345 in ShipStation while adding the SKU. 

If you'd like a pre-formatted CSV, download the sample CSV from the Import pop-up screen, or download the Order Import Template file at the bottom of this article. 

Common Order CSV Import Issues

If you experience missing data or an error message after a CSV import, the steps below can help you recover:

Missing Data

If you complete the import but certain order information appears to be missing from your orders in ShipStation, you may have missed a field in the mapping stage.

  • If you saved your mapping, check your saved field mapping. Edit the field mapping and save it under a NEW name. Then use the new field mapping for your imports going forward.

  • If you did not save your mapping, perform the import again and make sure all fields you wish to map have been assigned the correct ShipStation field in the drop-down menus. ShipStation will update the existing orders during the import process.

Error Messages

If you receive an "import failed" message, check the following:

  • Make sure your CSV does not include any invalid or special characters. As a general rule, dashes and periods are fine in any cells except the header row. However, currency symbols, accent marks, and other special characters within any cells of the CSV can cause the import to fail.

  • Check the type of characters used in certain fields in your CSV. For example, letters are not valid characters in the phone number field. The @ symbol is fine in the email field but may cause an error when used in other fields.

  • If the above steps do not appear to be the cause of your error, create a new CSV file and copy/paste your CSV data into the new file and save it. Then try the upload again. 

Additional Troubleshooting Resources

For further CSV import troubleshooting, review the CSV Import Troubleshooting article in the Troubleshooting section of our help centre

A store you can create in ShipStation to hold manual orders (orders you create directly in ShipStation or by CSV import, rather than importing them from a connected store). You can create as many manual stores as you need.

The method used in ShipStation to assign a specific piece of data from a source to its corresponding field in ShipStation. As in "field mapping" for order imports and "service mapping" for import rules.

The method used in ShipStation to assign a specific piece of data from a source to its corresponding field in ShipStation. As in "field mapping" for order imports and "service mapping" for import rules.