Troubleshoot CSV Order Imports

General notes you should be aware of when importing orders from a CSV file and troubleshooting tips if your import fails for any reason.

Template Required


Data Identifier

Order Number

Help Section

Import From a CSV

Troubleshooting Tips:

  • CSV imports can only create or update orders in a ShipStation Manual Store, which is chosen at the beginning of the import process. Each CSV import is limited to a single store.

    CSV Import Orders pop-up. Red box highlights the Import to Store dropdown
  • If no Manual Stores are active in the account, the Import Order action will not be available in the Other Actions menu.

    To learn how to create a Manual Store, review the instructions to add a manual store in the Connect a Store article.

  • All order numbers must be unique per store.

    If an Order CSV is imported into a store that includes Order Numbers that are already in use, ShipStation will attempt to update the existing orders using those Order Numbers. If the existing order is in a Shipped or Cancelled status, that order will not be updated.

  • When importing a CSV, blank fields in the CSV file will cause the corresponding field to be blank in ShipStation. The exceptions to this is Order Date, which will default to today's date if left blank.

  • When updating orders with a CSV import, the Buyer Name field cannot be updated. The Buyer Name is locked to the order after the initial import.

  • To create customer records for an order, or to connect orders to an existing customer record, you must include the customer Username in the CSV and map it to the Buyer Username field during the initial order import action.

    Order CSV field mapping pop-up with Buyer Username selected for the Buyer Username drop-down menu.
  • Each column header name should be unique. Do not duplicate column header names in the CSV file.

  • If you are unable to see the column header names in the import mapping screen, and instead only see the numerical value for the column header (F1, F2, F3, etc.) check your Saved Mappings for special characters, like the # symbol, in the Saved Mapping name.

    These special characters can cause ShipStation to improperly validate the column headers, even if you're using a different Saved Mapping. To resolve the issue, edit the name of the saved mapping to use only numbers and letters.

  • Do not add a period to the text in column headers.

    Adding a period on column headers - for example "Order No." - can cause errors upon import.

  • Use semicolons to display multiple options in the Item Options column.

    This column uses key:value pairs to display options such as color:blue. Semicolons will separate two key:value pairs, letting you create and display a second item option.

    EXAMPLE: color:blue;size:small will create two different item option rows for the product, and color:blue;size:small;material:cotton will create three rows of item options, etc.

    Without the semicolon, everything that follows the second colon will fail to display.

    Order import CSV with Item Options example showing key:value pair sample. "Color: Black; Size: XL; no bow"