Troubleshoot item library importing
If you have trouble importing your item catalogue, you may be experiencing an issue with the formatting or syntax of your Excel (.xlsx) or Comma Separated Value (.csv) spreadsheet.
This article provides advanced troubleshooting for your item catalogue import. Most issues can be resolved with the suggested troubleshooting steps below.
Before you begin
Troubleshooting steps may be done from your Square Dashboard or directly in your item library spreadsheet, depending on the issue.
Depending on the size of the item catalogue you’re trying to upload, correcting errors in your import spreadsheet may take a bit of time. We recommend troubleshooting your item library import outside of business hours, or when it may be least disruptive to your business.
The steps below are listed in order of least to most time intensive. If the first step solves the issue, there is no need to continue troubleshooting. If the issue is not resolved, follow the instructions in sequential order.
Step 1. General item import troubleshooting
The following instructions are general troubleshooting guidelines for common issues when importing an item catalogue.
For best results, use a supported browser and its last updated version, such as Google Chrome, Mozilla Firefox, Safari, or Microsoft Edge.
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 from your Item Library, click Actions > Export Library > Export.
- 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.
- 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).
- When editing the template, don’t:
- change any information in the Token column
- reorder any columns
- delete any empty columns
- 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.
Step 2. Troubleshooting specific item import errors
If there are errors with your spreadsheet, the item import tool will notify you and recommend steps to fix them. All errors must be resolved before your items can be imported. Here are the most common scenarios you may see.
Images cannot be uploaded via the Item Import Tool. Learn more on how to upload and manage item images.
If a spreadsheet contains simple errors, the import tool will give you the option to auto-resolve the errors and complete your import. Simple errors may include items and variations having differing descriptions, GTINs having an incorrect length, spreadsheet columns not matching Square attributes and more. You’ll have the option to approve or decline each type of auto-resolution error.
If your spreadsheet contains minor errors, the tool will import as many entries as possible and provide a downloadable error report. The report will show the error reason for each item that could not be imported so you can correct those entries on your spreadsheet. Make the necessary adjustments to your updated Excel file (not in the error report), save the Excel file, and attempt to import the document to your Dashboard again.
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).
Step 3. Correct 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 Square Dashboard.
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 zeros, below are some tips to help you with common formatting issues.
- Create a new spreadsheet in Microsoft Excel.
- Select File > Import from the main menu.
- Select CSV File > 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.
- Choose the New Sheet option > select OK to complete the import.