CSV and XLSX Format
Use this reference when preparing a spreadsheet (CSV or XLSX) for import into BatchCard. Every column, data type, accepted column name, and formatting requirement is listed below.
For a step-by-step walkthrough of the import process, see the import guide. For help with errors, see import errors.
Quick reference table
| Column | Required | Type | Example |
|---|---|---|---|
| Value | Yes | Number (0.01 to 2,000.00) | 25.00 |
| Code Prefix | No | Letters and numbers (A-Z, 0-9) | GIFT |
| Code Suffix | No | Letters and numbers (A-Z, 0-9) | 2026 |
| Recipient Email | No | Valid email address | customer@example.com |
| First Name | No | Text | Jane |
| Last Name | No | Text | Doe |
| Message | No | Text (max 255 characters) | Happy Birthday! |
| Expiration Date | No | Date (YYYY-MM-DD preferred) | 2027-12-31 |
| Note | No | Text | Corporate gift batch |
| Tags | No | Comma-separated text | corporate, holiday |
Detailed field specifications
Value (required)
The dollar amount of the gift card.
Range: $0.01 to $2,000.00
Accepted formats:
- Plain number:
25.00 - With currency symbol:
$25.00,EUR25.00 - With thousand separators:
1,000.00 - European format with comma decimal:
25,00or1.000,00
The app strips currency symbols automatically. It also auto-detects European comma-as-decimal format using a heuristic: if the last comma in the value appears after the last period, commas are treated as decimal separators.
Accepted column names: Value, Amount, Price, Cost, Card Value, Gift Card Value, Face Value, Denomination
Code Prefix
Characters added before the auto-generated random portion of the gift card code. For example, a prefix of "GIFT" produces codes like GIFT-XXXXXXXXXXXX.
Format: Cleaned to uppercase letters and numbers only. Special characters are stripped.
Length limit: The combined length of prefix and suffix cannot exceed 12 characters. The remaining characters are used for the random portion of the gift card code (minimum 8 random characters required, maximum total code length of 20).
If left blank, no prefix is added.
Accepted column names: Prefix, Code Prefix, Card Prefix
Code Suffix
Characters added after the auto-generated random portion of the gift card code. For example, a suffix of "2026" produces codes like XXXXXXXXXXXX-2026.
Format: Same cleaning and length rules as Code Prefix. Cleaned to uppercase letters and numbers only.
Length limit: Combined prefix and suffix cannot exceed 12 characters total.
If left blank, no suffix is added.
Accepted column names: Suffix, Code Suffix, Card Suffix
Recipient Email
The email address of the gift card recipient. Used for email notification delivery and Shopify customer lookup.
Format: Must be a valid email address (name@domain.tld). Cleaned to lowercase and trimmed of extra spaces.
If the email matches an existing Shopify customer, the gift card is linked to that customer. If no matching customer exists, one is auto-created with NOT_SUBSCRIBED marketing consent. No tags are applied to auto-created customers.
If left blank, the gift card is created without a recipient and no email is sent.
Accepted column names: Email, Recipient Email, Recipient, To, Send To, Customer Email, Email Address
First Name
The recipient's first name. Used to personalize the gift card notification email.
Format: Trimmed of leading and trailing spaces. No other cleaning is applied.
Accepted column names: First Name, Given Name, First, Recipient First Name, Customer First Name, Fname
Last Name
The recipient's last name. Used to personalize the gift card notification email.
Format: Trimmed of leading and trailing spaces. No other cleaning is applied.
Accepted column names: Last Name, Surname, Family Name, Last, Recipient Last Name, Customer Last Name, Lname
Message
A personal message included in the gift card notification email. The recipient sees this message when they receive their gift card.
Maximum length: 255 characters.
Format: Trimmed of leading and trailing spaces. No other cleaning is applied.
Accepted column names: Message, Personal Message, Gift Message, Note to Recipient, Greeting
Expiration Date
The date when the gift card expires. Must be a future date.
Accepted date formats:
YYYY-MM-DD(preferred): 2027-12-31MM/DD/YYYY: 12/31/2027DD/MM/YYYY(auto-detected when the first number is greater than 12): 31/12/2027DD-MM-YYYY: 31-12-2027DD.MM.YYYY: 31.12.2027- ISO 8601 with time: 2027-12-31T00:00:00Z
Expiration dates may be restricted in some jurisdictions. Many US states and Canadian provinces prohibit gift card expiration. The US CARD Act requires a minimum 5-year validity period where expiration is permitted. Check your local regulations before setting expiration dates.
If left blank, the gift card does not expire.
Accepted column names: Expiration, Expiration Date, Expires, Expires On, Expiry, Expiry Date, Valid Until
Note
An internal note visible only to store staff. Recipients do not see this note.
Format: Trimmed of leading and trailing spaces. No other cleaning is applied.
Accepted column names: Note, Internal Note, Admin Note, Notes, Comments
Tags
A comma-separated list of labels for organizing your batch. Tags help you filter and find batches later.
Example: corporate, holiday, Q4-2026
Format: Trimmed of leading and trailing spaces. No other cleaning is applied.
Accepted column names: Tags, Tag, Labels, Categories
Column name matching
BatchCard auto-matches your column headers to the fields listed above using a predefined list of accepted names. Headers are normalized before matching: converted to lowercase, and underscores, hyphens, periods, and backslashes are converted to spaces.
For example, all of these headers map to the same field:
Recipient Emailrecipient_emailRECIPIENT-EMAILrecipient.email
If a header does not match any accepted name, it appears as "Unmapped" in the column mapping step. You can manually assign it to the correct field using the dropdown, or set it to "Skip" if you do not need that column.
File format notes
- CSV files should use comma delimiters. Semicolons are also auto-detected.
- UTF-8 encoding is recommended. The app warns you if replacement characters (encoding problems) are detected in your file.
- XLSX files: If your workbook has multiple sheets, you can select which sheet to import using the sheet selector that appears below the upload area.
- XLSX sheet naming: Name your sheet "Gift Cards" for automatic detection. The app looks for any sheet with "gift card" in the name (case-insensitive). If no match is found, the first sheet is used. You can always switch sheets manually after uploading.
- Empty rows are ignored automatically.
- The header row must be the first row of the file (or the first row of the selected sheet).
File size and row limits
The maximum number of rows per import depends on your plan. File import is not available on the Free plan.
| Plan | Cards per month | Max rows per import |
|---|---|---|
| Free | 25 | File import not available |
| Starter | 500 | 500 |
| Pro | 2,500 | 2,500 |
| Business | Unlimited | 10,000 |
See Plan Limits for a full breakdown of what each plan includes.
Import templates
Both CSV and XLSX templates include all 10 columns with example data. The XLSX version includes clickable header links back to this documentation.
Formatting tips
- Values: Currency symbols are stripped automatically. Write
25.00or$25.00, both work. European comma-decimal format (for example,25,00) is auto-detected. - Emails: One email address per row. The app validates the format during import.
- Dates: Multiple formats are accepted. Use
YYYY-MM-DDfor the most reliable results. See Expiration Date for all accepted formats. - Empty optional columns: Leave them blank. Do not write "N/A" or "none."
- Trailing commas: Acceptable. Most spreadsheet apps handle this automatically.
Related
- Importing from CSV or XLSX: get started with your first import
- Importing Spreadsheets: detailed guide for preparing and importing files
- Import Errors: fix common import problems
Ready to try this? Install BatchCard free.
Create bulk gift cards from a CSV or form. Set up your first batch in minutes.
Install Free on Shopify