Managing Gift Cards with Bulk Actions

Overview

The Bulk actions feature allows you to create, send, update, or import a large number of gift cards at once, from a single file or form. This saves you significant time compared to managing gift cards one by one. This guide will walk you through how to use the bulk tools to manage your gift cards efficiently.

Accessing the Bulk Actions Page

1. In the app menu, click Bulk actions. You can also click Open bulk tools on the home page.

You will see a page with four tabs: Import from file, Generate, Bulk update, and Mass send. Each tab corresponds to a specific bulk action you can perform, and lists that action's past jobs under the form.

Preparing Your Data File

Import, Bulk update and Mass send (with Import file) work by uploading a CSV (Comma-Separated Values) file. Generate, and Mass send with Configure manually, use a form instead. You can create a CSV file using any spreadsheet software like Microsoft Excel or Google Sheets.

Key guidelines:

• The first row of your CSV file must be a header row that contains the exact field names (e.g., code, initial_value, email). Upper or lower case does not matter.
• Each subsequent row represents one gift card to be processed.
• Save the file as a comma-separated CSV (semicolons also work), up to 5 MB.
• We recommend downloading our template file (the template link on each tab) to ensure your data is formatted correctly.
• Tip: Before uploading a large file, try a small test file with just 2–3 rows to ensure everything is working as expected.

---

Using Your Own Gift Card Image

Every bulk action that uses a CSV file can give each gift card its own artwork. Add an image column to your CSV and put the URL of the picture in it — the card will be shown with that image on the gift card page and in the gift card email.

Step 1 — Upload your images to Shopify

1. In your Shopify admin, go to Content → Files.
2. Click Upload files and select the images you want to use.
3. Wait until each upload finishes.

Step 2 — Copy the image URL

1. Hover over the uploaded file in the list.
2. Click the link icon (Copy link) at the right side of the row. The full URL is now on your clipboard.
3. Paste it into the image column of the matching row in your CSV.

What the URL has to look like

A link copied from Content → Files looks like this:

https://cdn.shopify.com/s/files/1/0594/1241/4670/files/gift-card-birthday.png?v=1671206648

Requirements:

• It must be a full URL that starts with https://. Links starting with http:// or //cdn.shopify.com/... are rejected, and so is a bare file name such as gift-card-birthday.png.
• Keep the whole link, including the ?v=... part at the end — that is the file version Shopify uses for caching.
• The image has to stay in Content → Files. If you delete or replace the file later, cards pointing at it lose their artwork.
• Images hosted outside Shopify work too, as long as the link is a public https:// URL.

Recommended image

Property	Recommendation
Aspect ratio	5:3 (the same shape as the built-in designs)
Size	around 1000 × 600 px
Format	PNG, JPG or WebP
File size	under 2 MB, so emails stay light

How the image is chosen

• A value in the image column overrides the design selected on the page — this lets one file carry a different picture per row.
• On the Mass send tab, rows without an image value fall back to the design selected under Gift cards images.
• If a row contains something that is not a valid https:// URL, that row is marked as Failed on the job's Results page with the reason, and no gift card is created for it. Fix the URL and re-upload just those rows.

---

Issuing Cards in Other Currencies

If your store sells in several currencies through Shopify Markets, a bulk job can issue cards in any currency your markets enable — not only your store currency.

• Generate and Mass send (Configure manually): a currency picker appears next to the value field. On a single-currency store it stays hidden.
• Mass send (Import file) and Import from file: fill in the currency_code column, for example EUR. An empty column means your store currency.
• Bulk update: a card's currency cannot be changed. The column is only a check: a row naming a currency the card is not in fails, instead of adjusting the balance in money you did not mean.

A row naming a currency your markets have not enabled fails during upload, with the list of currencies you can use. No card is created for that row; the other rows are processed as usual.

Where the card can be spent is controlled by Cross-currency redemption on the eGift/Physical cards → E-Gift cards page (under Enable Shopify Markets support): leave it on the Shopify default, restrict the card to its own currency, or convert at your market's rate or the spot rate.

In analytics, dashboard totals stay in your store currency. Cards in other currencies are listed separately above the tiles with their own totals, because amounts in different currencies cannot be added into a single figure.

---

1. Generating Bulk Gift Cards

Use this feature when you want to create a batch of new gift cards but not send them to anyone yet. They are created in Shopify as active gift cards, ready to be handed out.

How to generate gift cards:

1. Navigate to the Generate tab.
2. Fill in the Gift card details form:
   • Value — Enter the monetary value for each gift card (e.g., 25.00).
   • Currency — Shown next to the value only when your Shopify Markets enable more than one currency. Pick the currency the cards are issued in. See Issuing cards in other currencies.
   • Number of gift cards — Specify how many cards you want to create with these settings, up to 100,000 per job.
   • Prefix (optional) — Enter up to 4 characters to add to the beginning of each generated gift card code. This can help you identify a specific batch of cards later.
   • Code length — Choose the length of the unique gift card code that will be generated (between 8 and 16 characters). Batches over 10,000 cards use at least 14 characters, so codes don't collide.
   • Note (optional) — Add an internal note for this batch of cards. This note is not visible to customers.
   • Expiration date — Select No expiration date if you don't want the cards to expire, or Set expiration date to choose a specific date when the cards will become invalid.
3. Under Gift cards images, click the design you want the generated cards to use.
4. Click the Start generation button.

The system will then create the specified number of gift cards with these settings. The job appears in the Generate jobs list below the form. Click its note to open the Results page and click Download results (csv), or select the job in the list and click Download CSV or Download PDF (a print-ready file with one card per page, showing the code and its QR code).

Special option: Generate without import

Check the Generate without import box if you plan to use these gift card codes for physical, printed cards. The codes are generated for printing only: no Shopify gift cards are created, so nothing can be spent yet. Value, Note and the expiration date are disabled in this mode. When the printed cards arrive, bring the codes in with Upload codes on the Physical gift cards tab, or register each card as it is sold. See Physical Gift Cards.

---

2. Sending Bulk Gift Cards

Use this feature to create and immediately email gift cards to a list of recipients. This is perfect for marketing campaigns, corporate gifting, or customer rewards. Each email address gets its own card.

On the Mass send tab, choose Configure manually to type the email addresses into a form, or Import file to upload a CSV.

Configure manually:

1. Fill in Value (and the currency, if your markets enable more than one), and optionally Prefix, Code length, Message, From and Note.
2. In Emails, enter the recipients' email addresses separated by commas.
3. Pick a design under Gift cards images and set the expiration date.
4. Click Start mass send.

Import file, required & optional fields:

Field Name	Required	Description
initial_value	Yes	The starting balance of the gift card.
currency_code	No	Three-letter currency code the card is issued in, e.g. EUR. Leave empty for your store currency. See Issuing cards in other currencies.
email	Yes	The email address of the person receiving the gift card.
message	No	A personal message to include in the gift card email.
from	No	The sender name shown with the gift card.
note	No	Internal note saved on the card. Not visible to customers.
expires_on	No	The date the gift card expires, in YYYY-MM-DD format.
image	No	https:// link to the artwork for this card. Overrides the design selected on the page. See Using Your Own Gift Card Image.

Note: Every card in a Mass send job is emailed automatically. You don't need any notification columns.

How to send gift cards from a file:

1. Open the Mass send tab and select Import file.
2. Download the template and prepare your CSV file with the required columns. Ensure all email addresses are correct.
3. Upload your CSV file and, optionally, add a Mass send note.
4. Pick the default design under Gift cards images.
5. Click the Start mass send button to begin the process.

---

3. Updating Bulk Gift Cards

Use this feature to make changes to existing gift cards in your system. You can change their balance, expiration date, note, customer, recipient or artwork, or disable them.

Required & optional fields:

Field Name	Required	Description
id	id or code	The Shopify gift card ID.
code	id or code	The full gift card code you want to update. Spaces and dashes are ignored.
balance	No	Set a new balance for the gift card. Use + or - prefix to increment or decrement balance (e.g. +10 or -10).
currency_code	No	A check, not a change. A gift card's currency can never be changed, so a row naming a different currency than the card holds fails instead of adjusting the balance.
expires_on	No	Change the expiration date. Use YYYY-MM-DD format.
note	No	Replaces the internal note. If the column is empty or missing, the card's existing note is cleared, so repeat the old note if you want to keep it.
disabled	No	Set to 1 to disable the card. Please note that this action cannot be reverted. Leave it empty to keep the card active.
recipient_email	No	The email address of the person receiving the gift card.
customer_email	No	The email address of the customer the card belongs to.
notify_customer	No	Set true (or 1, yes) to email the card to the customer in customer_email.
notify_recipient	No	Set true (or 1, yes) to email the card to the recipient in recipient_email.
image	No	https:// link to new artwork for the card. Replaces the picture the card was issued with. See Using Your Own Gift Card Image.

Note: Updating the image re-skins a card that already exists — the customer sees the new picture the next time they open the gift card page or receive an email about it.

How to update gift cards:

1. Open the Bulk update tab.
2. Download the template and prepare a CSV file containing the code (or id) of each gift card you wish to modify, along with the fields you want to update.
3. Upload the file and click Start import.

---

4. Importing Existing Gift Cards

Use this feature to migrate gift cards from another system into our platform. This allows customers to use their existing gift cards from your previous provider.

Required & optional fields:

Field Name	Required	Description
initial_value	Yes	The current balance of the gift card at the time of import.
currency_code	No	Three-letter currency code the card is issued in, e.g. EUR. Leave empty for your store currency. See Issuing cards in other currencies.
code	No	You can specify an existing code: 8 to 20 letters and numbers, spaces and dashes are ignored. If not set, the app will generate a gift code during the import.
expires_on	No	The expiration date of the imported card, in YYYY-MM-DD format.
note	No	Internal note saved on the card.
email	No	The customer the card belongs to. The customer is found or created in Shopify by this email. No email is sent unless notify_customer is set.
customer_email	No	Same as email. Used instead of it when both are filled.
recipient_email	No	The email address of the person receiving the gift card.
notify_customer	No	Set true (or 1, yes) to email the card to the customer.
notify_recipient	No	Set true (or 1, yes) to email the card to the recipient.
image	No	https:// link to the artwork for this card. See Using Your Own Gift Card Image.

How to import gift cards:

1. Open the Import from file tab.
2. Download the template and prepare your CSV file. Only the initial_value column is required.
3. Upload your file, optionally add an Import note, and click Start import.

---

Monitoring Your Bulk Jobs

After starting a bulk action, its job appears in the list under the form on the same tab (Import jobs, Generate jobs, Update jobs or Mass send jobs). Your job will be processed in the background, so you can safely navigate away from the page.

The jobs list shows, for each job:

• Done — rows processed successfully.
• In progress — rows waiting or being processed.
• Failed — rows that could not be processed.

Click a job's note to open its Results page. It shows every row with its status (Success, In progress, Retrying or Failed) and, for failed rows, the error message, so you can correct your file and re-upload just those rows. Check Autorefresh import jobs to keep the page updating, and click Download results (csv) to get all rows with their status and errors.

Common Errors & Troubleshooting

• "Incorrect format of CSV file" — The file could not be read as a CSV. Check that it is saved as CSV (not Excel) and that the header row is present. Please use our provided template.
• "Missing mandatory fields" — The upload was refused because a required column is missing: initial_value for Import, initial_value and email for Mass send, id or code for Bulk update. The check reads your first row, so also make sure that row has a value in the required column.
• "Invalid code format" — A code in that row is too short, too long, or contains characters other than letters and numbers. Use 8 to 20 letters and numbers; spaces and dashes are ignored.
• "An identical job ... is still running" — You started the same job again (same file, or same settings) while the first one is still being processed. Wait for it to finish instead of starting it twice.
• Rows marked "Retrying" — The row hit an error, for example Shopify's rate limit, and will be tried again automatically. No action is needed. A row is marked Failed only after its retries run out.