How to Import Active Gift Card Codes
This guide explains how to import existing gift cards into Expresso Gift Cards, including support for custom codes from legacy systems.
Overview
The import feature allows you to bring in gift cards via CSV, with optional custom codes to maintain continuity for your customers. You can mix and match cards with custom codes and auto-generated ones in the same import.
Important: When email notifications are enabled, recipients will receive an email from Shopify for each gift card created. If you're importing existing gift cards and don't want to notify customers, make sure to uncheck "Send email notifications to recipients" before creating.
CSV File Format
Your CSV file should include these columns:
| Column | Required | Description | Example |
|---|---|---|---|
firstname | Yes | Recipient's first name | John |
lastname | Yes | Recipient's last name | Smith |
email | Yes | Recipient's email address | john@example.com |
amount | Yes | Gift card value | 50.00 |
message | No | Personal message sent to the recipient (max 200 characters) | Happy Birthday! |
note | No | Internal note visible only in your Shopify admin | Loyalty reward Q1 |
expireson | No | Expiration date | 2027-12-31 |
code | No | Custom gift card code | HOLIDAY2024 |
Flexible Column Headers
Column headers are flexible and case-insensitive. The app recognizes common variations:
| Field | Accepted Headers |
|---|---|
| First Name | firstname, first, fname, givenname |
| Last Name | lastname, last, lname, surname, familyname |
email, emailaddress, mail | |
| Amount | amount, value, balance, price |
| Message | message, msg |
| Note | note, notes, internalnote |
| Expires On | expireson, expires, expirydate, expiry, expirationdate, expiration |
| Code | code, giftcardcode, cardcode |
Amount Formatting
Currency symbols and comma separators are automatically stripped. All of these are valid:
25.00$25.00€100.00£501,000.50$2,500.00
Date Formats
The app accepts multiple date formats and converts them automatically:
YYYY-MM-DD(e.g.,2027-12-31)MM/DD/YYYY(e.g.,12/31/2027)DD-MM-YYYY(e.g.,31-12-2027)
Dates in the past will be flagged as errors during validation.
Email Validation
The app validates email addresses and automatically corrects common typos:
gmial.com→gmail.comgmai.com→gmail.comyahooo.com→yahoo.comhotmial.com→hotmail.com
Corrections are shown as warnings so you can review them before creating.
Custom Code Requirements
- Codes are optional — leave the field empty and Shopify generates one automatically.
- Codes must be unique across your Shopify store.
- Codes are case-sensitive.
- Invalid or duplicate codes will cause individual card creation to fail. The app reports which cards succeeded and which failed.
Performance note: Gift cards with custom codes are processed individually rather than in bulk. This is slower than auto-generated codes but necessary because Shopify requires individual API calls for custom codes.
Controlling Email Notifications
By default, recipients receive their gift card via email when it's created. To suppress notifications:
- Prepare your import as usual.
- Before clicking "Create Gift Cards," uncheck "Send email notifications to recipients."
- Gift cards will be created silently — no emails sent to recipients.
This is especially useful when importing existing gift cards where customers already have their codes.
Mixed Imports
You can import a mix of cards in the same CSV:
- Some rows with custom codes
- Some rows with empty code fields (auto-generated)
This gives you flexibility when migrating from legacy systems where only some gift cards have known codes.
Best Practices
- Disable emails for legacy imports. If you're importing existing gift cards, uncheck email notifications so customers aren't confused by a new email for a card they already have.
- Test first. Import a small batch (5-10 cards) to verify your CSV format and settings before importing a larger file.
- Keep batch sizes manageable. For large imports, consider splitting into batches of a few hundred cards, especially if using custom codes.
- Back up your codes. Keep a copy of your original CSV for reference.
- Ensure unique codes. Verify that all custom codes are unique before importing. Duplicates will cause failures for those specific cards.
- Use Save Draft. After importing your CSV, review the data in the spreadsheet editor and click "Save Draft" if you need to make adjustments before creating.
- Check the History tab. After creation, review the results in the History tab to confirm all gift cards were created successfully.
Scheduling Imports
If you want to delay the creation of your imported gift cards:
- Import your CSV and review the data.
- Click "Schedule for Later" instead of "Create Gift Cards."
- Choose your desired date and time.
- Optionally enter a notification email to be alerted when the import completes.
- Manage scheduled imports from the Scheduled tab.
Need more help? Contact our support team at support@anatolilabs.com
Was this article helpful?
Your feedback helps us improve our documentation.