How to import gift cards from a CSV file

This guide explains how to use Import gift cards in the embedded Shopify app. It matches how the app validates rows and talks to Shopify.

Before you start (requirements)

1. Shopify customers must exist in your store. If you use customer_email or recipient_email, that address must belong to a customer already created in Shopify Admin (Customers) for your shop. The app looks up customers by email via the Shopify Admin API. If the email is not found, the row fails with an error such as "Customer not found for email: …" or "Recipient customer not found for email: …".
2. Use either ID or email (not both for the same role). For the gift card owner / giver: provide customer_id or customer_email (one is enough; if both are set, customer_id is used when present). For a recipient (optional): provide recipient_id or recipient_email (same rule).
3. initial_value is required on every data row. It must be a positive number (e.g. 50 or 50.00). This is the only column the file must always include in the header and in each row you want to import.
4. Plan and limits. Imports count toward your subscription usage (rows per billing cycle). The Import page shows your current usage and caps. The app may also enforce maximum rows per file and maximum file size (see the numbers on the Import screen).
5. File format. Use a .csv file with a header row as the first line. Column names are matched case-insensitively (e.g. initial_value or Initial_Value).

CSV columns (reference)

*You may omit both customer_id and customer_email only if you intentionally create a gift card without attaching a customer (Shopify allows that). To assign the card to someone in your store, you must supply one of them—and if you use email, that person must already exist as a customer in Shopify.

Customer vs recipient (important)

• If there is no recipient (no recipient_id / recipient_email), the customer is the person receiving the gift card.
• If there is a recipient, the customer is the giver and the recipient is the one receiving it.

Step-by-step: Import gift cards (in the app)

1. Open the app. In Shopify Admin, open Apps → your app → the Import gift card tab.
2. Review usage and limits. Check import usage and maximum rows / file size on the page.
3. Download a sample (recommended). Click Download Sample Template, pick a template, and replace sample rows with your data. Keep the header row.
4. Prepare your CSV. Row 1 = headers; each following row = one gift card. Every customer_email / recipient_email must exist in Shopify Admin → Customers. Every row must have a valid initial_value.
5. Read format details (optional). Click View CSV Format Instructions in the app.
6. Upload the file. Choose your .csv and start the import (or preview if offered).
7. Wait for processing. Large files may take time; follow on-screen progress.
8. Review results. Open Gift card log / import history or download errors, fix rows, and re-import if needed.

Scheduled imports

If you use Scheduled imports, the CSV rules are the same. Follow the Scheduled imports tab in the app for upload and scheduling.

Common errors (quick reference)

Summary

1. Create or verify customers in Shopify before using their emails in the CSV.
2. Build a CSV with a header and required initial_value on each row.
3. Use customer_id or customer_email (and optionally recipient_id or recipient_email) following the giver/receiver rules above.
4. Import from the app’s Import gift card tab, then check logs / errors for failed rows.

For exact caps (rows per file, MB, timeout), use the numbers shown on the Import Gift Cards page in the app.