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 that you’re using the most up-to-date template from your Square Dashboard. To access it from your Item Library, click Actions > Import Library > download the 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 from what the template downloaded as.
-
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 the 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 comma-separated value (.csv) format files to support bulk importing and exporting of your item library and inventory.
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 Items page 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.
Note: If you’re attempting to transfer libraries between accounts, there are some additional steps you’ll 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 item import 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’s 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’re 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 (e.g. 0012345 will become 12345) or convert your SKUs to scientific notation (e.g. 12345678999 will become 1.2346E+10).
While we recommend avoiding the use of SKUs that contain leading zeros, 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.
Click Finish. (See image)
Choose the New Sheet option and select OK to complete the import.
If you have exhausted all the troubleshooting steps, contact Square Support for further assistance.