Import Errors

If you run into an error while importing a spreadsheet (CSV or XLSX), find the error below and follow the steps to fix it.

File upload errors

These errors appear immediately after you upload your file (Step 1 of the import flow).

"Please upload a CSV or XLSX file."

Cause: The file has an unsupported format. BatchCard only accepts .csv and .xlsx files.

Fix:

1. Save your file as CSV or XLSX format.
2. If you are using Google Sheets, go to File > Download > Comma Separated Values (.csv).
3. Upload the new file.

"No header row detected. Please use the template for correct column headers."

Cause: The first row of the file does not contain recognizable column headers.

Fix:

1. Add a header row as the first row of your file with column names like "Value", "Recipient Email", and so on.
2. Download the template from the app for the correct format.
3. Save and re-upload.

"File contains headers but no data rows. Please add data and try again."

Cause: The file has a header row but no data beneath it.

Fix:

1. Add at least one row of gift card data below the header row.
2. Save and re-upload.

"File contains X rows. Maximum is 10,000 rows per import."

Cause: The file exceeds the maximum row limit.

Fix:

1. Split your file into smaller files of 10,000 rows or fewer.
2. Your plan may have a lower limit: Starter allows 500 rows, Pro allows 2,500 rows, and Business allows 10,000 rows.
3. Upload each file separately.

"This file may have encoding issues. Try saving it as UTF-8 and re-uploading."

Cause: The file contains characters that could not be read properly. This usually happens when the file was saved with a non-UTF-8 encoding.

Fix:

1. Open the file in your spreadsheet application and re-save it.
2. In Excel: go to File > Save As and choose CSV UTF-8 (Comma delimited) as the format.
3. In Google Sheets: download as CSV (Google Sheets always uses UTF-8).
4. Re-upload the new file.

Column mapping errors

These issues appear during the column mapping step (Step 2 of the import flow).

Unmapped columns showing a "caution" badge

Cause: The app could not auto-match a column header to a known BatchCard field.

Fix:

1. Use the dropdown to manually assign the column to the correct field.
2. If you do not need that column, set it to "Skip."
3. Check the format reference for the full list of accepted column names.

"Value" column not mapped

Cause: No column in your file was recognized as the Value field. The Value column is the only required field.

Fix:

1. Make sure one of your columns has a header like "Value", "Amount", "Price", or any of the accepted names for Value.
2. You can also manually map any column to "Value" using the dropdown.

Row validation errors

These errors appear during the validation step (Step 3 of the import flow). Each error is shown next to the affected row.

"Value is required"

Cause: The Value cell is empty for this row. Every row must have a gift card value.

Fix: Add a number to the Value column for this row. For example: 25.00.

"Invalid number format"

Cause: The value could not be read as a number after removing currency symbols and formatting.

Fix: Use a plain number like 25.00 or 25. Remove any text or special characters other than digits, commas, periods, and currency symbols.

"Value must be between $0.01 and $2,000.00"

Cause: The gift card value is outside the allowed range.

Fix: Change the value to be at least $0.01 and no more than $2,000.00. This is Shopify's gift card value limit.

"Invalid email format"

Cause: The email address does not match a valid format.

Fix: Check for typos, a missing @ symbol, or a missing domain. A valid email looks like: name@example.com.

"Unrecognized date format. Use YYYY-MM-DD."

Cause: The expiration date could not be read in any accepted format.

Fix: Use the format YYYY-MM-DD (for example, 2027-12-31). Other accepted formats: MM/DD/YYYY, DD/MM/YYYY (when day is greater than 12), DD-MM-YYYY, DD.MM.YYYY. See the format reference for the full list.

"Expiration date must be in the future"

Cause: The date is today or a past date.

Fix: Set the expiration date to a future date.

"Message cannot exceed 255 characters"

Cause: The message text is longer than the 255-character limit.

Fix: Shorten the message to 255 characters or fewer.

"Code prefix + suffix cannot exceed 12 characters"

Cause: The combined length of the code prefix and code suffix is more than 12 characters.

Fix: Shorten the prefix, the suffix, or both so their total length is 12 characters or fewer. The remaining characters are reserved for the random portion of the gift card code (minimum 8 random characters).

"Import exceeds the maximum of 10,000 rows. Please split your file into smaller batches."

Cause: The file has more than 10,000 data rows.

Fix: Split your file into multiple files with 10,000 or fewer rows each. Your plan may have a lower limit: Starter allows 500, Pro allows 2,500, and Business allows 10,000.

Common issues and fixes

These are common problems that do not always produce a specific error message.

Values showing as $0.00 or incorrect amounts

Your file may use European number formatting (comma as decimal separator, for example 25,00). The app auto-detects this in most cases, but if values look wrong after mapping, check that the original file uses consistent formatting throughout.

Dates being misinterpreted

Ambiguous dates like 03/04/2027 could be March 4 or April 3, depending on your locale. The app assumes MM/DD/YYYY (US format) unless the first number is greater than 12.

Special characters or accents appearing as garbage text

This is an encoding issue. Re-save the file as UTF-8.

• Google Sheets: Download as CSV. Google Sheets always uses UTF-8.
• Excel: Go to File > Save As and choose CSV UTF-8 (Comma delimited).

XLSX file shows the wrong sheet

If your workbook has multiple sheets, the app defaults to the first sheet. Use the sheet selector dropdown that appears below the upload area to switch to the correct sheet.

Template download not working

Template downloads require an active Shopify session. If the download fails, try refreshing the page and clicking the download button again.

Still need help?

If your issue is not listed here, contact us at support@batchcard.app. Include the error message and, if possible, a sample of the rows causing the problem (with any sensitive data removed).