Import Item Library Troubleshooting
If you have trouble importing your item library, you may be experiencing an issue with your Excel (XLSX) or Comma Separated Value (CSV) spreadsheet.
Troubleshoot Item Import Tool
General Formatting
Try these troubleshooting steps to resolve common file formatting issues:
Make sure you’re using the most up to date template from your Square Dashboard. To access it, visit Items > click Actions > Import Library and select Download template.
Be sure to save the file as XLSX or CSV format. The item import tool won’t work with XLS, XLSM or any other file type.
Don’t change the file name.
-
When editing the template don’t:
change any information in the Token column
reorder any columns
delete any empty columns
Remove any commas from text you’ve added to the file (you can add them back to your item names, descriptions, option sets or modifiers once they’ve been imported to your library).
Double check that all of your items have unique names.
Items and their variations must have same category and description.
If you’re transferring item libraries between Square accounts or creating your item library for the first time, tax rates and modifiers must be manually created for the new library.
Import/Export File Format
Square uses Excel (XLSX) and a comma-separated value (CSV) format file to support bulk importing and exporting of your item library and inventory.
Note: The file format for Import/Export has changed to support more complexity in your item library and improve support for multiple locations.
Before you attempt to make changes to your library, export a copy of your item library in the new file format. If you need to revert to a recent version of your Item Library, you can undo an item import from the Itemspage of your online Square Dashboard > Actions > Undo Catalogue.
Using Undo Catalogue will not impact stock counts. However, stock actions relating to Inventory tracking (on/off toggle), inventory alerts, Default Unit Cost and Default Vendor information will be rolled back.
Refer to the Export File Field Descriptions table above for more details about the columns in your Import/Export file format.
Note: If you are attempting to transfer libraries between accounts, there are some additional steps you will need to take.
Number of Items
The item import tool can support up to 30,000 items in a single upload. If you need to upload more than 30,000 items, separate items into multiple files to import separately. When importing multiple files, do not select “Replace existing item library” as this will overwrite your item library in Square with the new file. If you’re still having issues, contact us for assistance.
Browser
For best results, use a supported browser, such as Google Chrome, Mozilla Firefox, Safari 6 or later, or Microsoft Edge. If you have trouble with your browser, try the following troubleshooting tips.
Common Errors
If there are errors with your spreadsheet, the item import tool will notify you and recommend steps to fix them. Here are the most common scenarios you may see:
If the file type cannot be read, the item import tool will display an error message asking you to export a new file and try again. Each file must contain the same column headers as the template file.
Here are the most common errors showing up in the Error Report
- Item and variation content not matching (e.g. an item and its variations must have the same category).
- Missing required fields (e.g. item name).
- Option set issues (e.g. all item variations using option sets must have both an option set name and an option value).
- Incorrect cell formatting (e.g. the GTIN value must be 8, 12, 13, or 14 digits long; GTIN can only contain numbers 0-9, no special characters).
All variations of an item must have the same category, description and item name. If a spreadsheet contains different descriptions or categories for variations of an item, you can automatically update the variations to match. For example, if you have different descriptions for each variation of an item, we will only import the description from the first row and ignore the rest as only one description and category are allowed per item in your Item Library. You can always skip this step to update manually in the error report.
If your spreadsheet contains errors, the tool will import as many entries as possible and provide a downloadable error report of the remaining items with errors. The report will show the error reason for each item that could not be imported so you can correct those entries on your spreadsheet. Directly edit the file, save it and try importing again to resolve errors.
Item Image Errors
Images cannot be uploaded via the Item Import Tool. When uploading an image to items in your Point of Sale, the image for that item will also update across your Square Online site or Square for Retail. It is not possible to have different images for the same items across Point of Sale, Square Online or Square for Retail at this time.
SKU Errors
If you’re using the CSV file format and receive an SKU error, check your import file to see if data in the SKU column is formatted in scientific notation, e.g. 2.68435E+17. If you see this, take the following steps:
With the item import CSV open, select the SKU column so the entire column is highlighted.
Right-click on the column > select Format Cells.
Select Number > and change the decimal places to 0.
Click OK.
Click File > Save As, and make sure the file format is saved as Comma Separated Values (CSV).
Click Save.
Import this new file to your online Square Dashboard.
SKU Formatting
Note: The following only applies if importing using a CSV file format, not Excel (XLSX).
While you are able to import the CSV data into a spreadsheet, if your item library contains SKUs do not open the CSV file directly as some spreadsheet editors (i.e. Excel, Numbers, etc.) will modify your SKUs in unexpected ways. For instance, the spreadsheet editor may remove leading 0s (ex. 0012345 will become 12345) or convert your SKUs to scientific notation (ex. 12345678999 will become 1.2346E+10).
While we recommend avoiding the use of SKUs that contain leading 0’s, below are some tips to help you with common formatting issues.
Import CSV data in Microsoft Excel
Create a new spreadsheet in Microsoft Excel.
Select File and Import from the main menu.
Select CSV File and click Import.
Choose the CSV file that you exported from your item library and click Get Data.
-
Your Import Wizard pop-up will appear.
Click Next and ensure that only the Comma Delimiter is checked, click Next again.
Scroll over to the SKU column (click to select the SKU column) and change the column data format to Text.
Press Finish. (See image)
Choose the New Sheet option and press OK to complete the import.
