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
Try these troubleshooting steps to resolve common 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 your option > click Next > Download our 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.
When editing the template, don’t change any information in the Token column or delete any empty columns.
Don’t change the file name.
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.
If you’re transferring item libraries between Square accounts, tax rates and modifiers must be manually created for the new library.
Number of Items
The item import tool can support up to 30,000 items in a single upload. If you need to upload over 30,000 items, you can import multiple files by importing a single file first. Afterwards, you’ll import the remaining files using the Modify option instead of Replace All Items. If you’re still having issues, contact us for assistance.
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.
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 > change the decimal places to zero.
Click File > Save As, and make sure the file format is saved as Comma-Separated Values (CSV).
Import this new file to your online Square Dashboard.
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 zeros (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 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 ticked. 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.
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 import changes to your library it is recommended you export a new 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’re attempting to transfer libraries between accounts, there are some additional steps you will need to take.
Item Import Errors
If there are any items on your spreadsheet that have errors, the item import tool will notify you of the errors. If a spreadsheet can’t be read, the item import tool will display an error message asking you to re-export a new file and try again. All errors must be resolved before your items can be imported. Common errors may include incorrect SKU formatting, items and variations having differing descriptions, GTINs having an incorrect length, spreadsheet columns not matching Square attributes and more.
If the item import tool detects errors with your spreadsheet during the import process, you will also have the option to download error report. The error report is a downloadable file that will have item/row-specific errors listed in a new column titled Errors. Directly edit the file and try importing again to resolve errors.
Item Image Errors
If you are having trouble importing or uploading your item library images, we suggest double-checking that your images meet the following specifications:
Ideal photo dimensions are square (same width and height) and up to 2,560 x 2,560 pixels.
Supported image types are JPG, JPEG, PNG, SPIN and GIF files.
Images that are HEIC format, 360 degrees or 3D are not supported.
Images can be up to 20 MB in size, but less than 500 KB is optimal.
The maximum number of images per item is 250.
Note: Images can’t 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.