Troubleshooting¶
Use the table of contents to jump to your issue, or search for a keyword.
Gift Card Email Issues¶
The recipient didn't receive the gift card email¶
Check these in order:
-
Spam/junk folder — ask the recipient to check, including Promotions and Updates tabs. Gift card emails occasionally trigger spam filters.
-
Email address typo — find the card in the Gift cards sending queue (see Troubleshooting Missing Gift Cards) and check the address. One wrong character means the email went elsewhere. Gift Card Hero can't detect a wrong address, so a mistyped one still shows Sent.
-
Queue status — the queue shows Scheduled (waiting for its delivery date), Sending, Sent or Failed. Failed means Gift Card Hero gave up after repeated attempts; click the email address to fix it and save, which sends the card again.
-
Scheduled delivery — if the buyer chose a future delivery date, the status is Scheduled and nothing is sent until that date.
-
Sender domain — if you send from your own domain, check its SPF and DKIM records. A misconfigured record can make mail land in spam or be dropped. If reminders or redemption notifications go through your own mail server, check its connection under Settings → Integrations.
-
Send it again — open the gift card in Shopify admin (Products → Gift cards) and use Resend Gift Card in the Gift Card Management block. You can send it to the customer, the recipient, the store admin or any address you type. See Gift Card Admin Block.
The gift card email looks broken (styling issues)¶
- Email clients often block external images by default. If only the pictures are missing, the recipient can choose to show images.
- Generate the template again on Settings → Email template and check the preview that opens. If it looks right there but wrong in Gmail or Outlook, the issue is the email client. Keep custom HTML simple and avoid CSS background images; use
<img>tags instead. - If you pasted the template into Shopify's gift card notification (Settings → Notifications → Customer notifications → Gift card created), paste the freshly generated one over it. See Email Templates.
The email shows raw code such as {{ gift_card.code }}¶
The template in Shopify's notification editor has a syntax error, so Shopify prints the placeholders instead of replacing them. Common causes are a missing }} or %}, or text that was cut off when pasting. Generate the template again on Settings → Email template, copy it, and replace the whole notification template in Shopify.
Missing Gift Cards¶
If a customer says they haven't received their gift card, follow the steps in Troubleshooting Missing Gift Cards. In short:
- Confirm the card exists in Shopify admin → Products → Gift cards.
- Check its status in the Gift cards sending queue (home page → Recent gift card queue → View full report).
- Fix the address and save, or resend from the Gift Card Management block.
- If the card can't be resent, issue a replacement with Issue e-Gift card.
Balance Check Widget¶
The widget doesn't appear on my storefront¶
-
App embed is off — on the home page, look at App Blocks Status. If your live theme shows Disabled, click Activate app embed, switch Gift Card Hero on in the theme editor and Save. See Installation & Setup.
-
Widget is switched off — open Balance widget in the left navigation. If the page shows Gift card balance widget is Disabled, click Enable. (Some stores see a shorter version of this page without that switch; there the widget is controlled by the app embed alone.)
-
Wrong place — the widget lives on your balance check page (
https://[your-store].myshopify.com/a/gifthero/balance) or wherever you added<div class="sc-hero-checker-container"></div>. When you add that code to a page, use the editor's HTML mode (the<>button), otherwise the tags are escaped. See Balance Check Widget. -
Cache — hard-refresh the storefront (Ctrl+Shift+R, or Cmd+Shift+R on Mac).
-
Old theme — Gift Card Hero shows We support only manual install for Shopify theme 1.0 on themes that predate Online Store 2.0. Click Contact support and we'll help you install it by hand.
The balance check says it can't find my card¶
The balance check looks cards up by the full code only. Typing the last four characters, or a partial code, returns nothing. Ask the customer to enter the whole code from their email.
The widget shows a wrong balance or status¶
If a customer has just spent the card, reload the page and check again. An expired card reads Expired on followed by the date, not "Active". If balances are consistently wrong by a fixed amount, contact support.
Gift Card Code Issues¶
"Invalid gift card code" at checkout¶
-
Typo — codes are case-insensitive, but every character must be correct. Check
0(zero) againstO(letter O) and1(one) againstI(letter I). -
Card disabled — the card may have been disabled. Check its status in Shopify admin → Products → Gift cards.
-
Card expired — check the expiry date on the card. An expired code no longer works.
-
Card is from another store — a card from a different Shopify store that isn't in your Multi-Store network won't work at your checkout.
-
Zero balance — a fully used card has nothing left to apply.
-
Currency — a card issued in another currency may not be accepted in yours. Check Cross-currency redemption on the E-Gift cards tab. See the FAQ.
A code is being rejected at POS but works online¶
Paying with a gift card at the register is handled by Shopify POS itself. The settings on POS tools → Shopify POS only control what staff can do in the Gift Card Hero tile (registering cards and changing balances), so none of them can turn a code away at checkout. Make sure the card isn't expired, disabled or from another store, as above.
If staff can't add to a balance, that is a different thing: see Reload or register isn't available in POS.
POS Issues¶
The Gift Card Hero tile is missing from Shopify POS¶
The tile isn't added automatically. In the Shopify POS app:
- Press Add tile.
- Go to Apps.
- Select Gift Card Hero.
- Press POS UI Extension. (The App link option also exists but is deprecated.)
- Press Done.
The same steps are in the Add the tile to Shopify POS card on POS tools → Shopify POS in Gift Card Hero. If the app isn't in the list, update the Shopify POS app to the latest version and, on iPad, force-close and reopen it. See POS Integration.
Reload or register isn't available in POS¶
On POS tools → Shopify POS, check Register gift cards and Balance changes. If Register gift cards is unticked, the Register Gift Card button in the tile says "Gift card registration is not allowed." If Balance changes is set to Off, Reload Gift Card says "Gift card reload is not allowed." Turn the setting back on and save. With Deduct only, staff can spend from a card but not add to it.
"Failed to load" error in the POS tile¶
This usually means the POS device can't reach Gift Card Hero. Check:
- Is the device connected to the internet?
- Is a firewall or content filter blocking outbound connections?
- Does it work after switching from Wi-Fi to cellular (or the other way round)?
If your till isn't Shopify POS, see Gift Hero POS: Gift Cards on Any POS.
Bulk Operations¶
The bulk job seems stuck¶
Large jobs run in the background and can take a while, depending on Shopify's rate limits.
- Open the job from Bulk actions and tick Autorefresh import jobs on the results page.
- Each row has a status: Pending and In progress are still being processed, Retrying means a temporary error and Gift Card Hero will try again, Success is done, and Failed means Gift Card Hero gave up. Click Failed to see the error.
- A running job can't be paused or cancelled. If it makes no progress for a long time, contact support with the job's link.
Rows in my bulk send show "Failed"¶
Click the Failed badge on the row to read the error. For Mass send, Gift Card Hero checks addresses before it starts and tells you which ones are invalid. For a CSV, the usual cause is extra spaces or hidden characters in the email column, often from Excel. Open the file in a text editor, fix it, and upload only the failed rows again. Download the full list with Download results (csv).
Bulk send completed but some recipients say they didn't get an email¶
- Check the results. Rows marked Success were sent; ask those recipients to check spam.
- Corporate mail servers often filter bulk mail from new senders.
- If you send many emails at once, make sure your sender domain's SPF and DKIM records are set up.
Analytics¶
My dashboard shows $0 for all metrics¶
- Permission — Analytics needs access to all your order history. If you see Additional permissions required, click Give the app additional scope and approve it in Shopify.
- Sync — analytics are built from synced data. Click Sync Data on the Analytics page and choose Sync for period or Sync for all time. A banner shows progress. If a sync stalls you can Cancel sync and retry.
- Date range — check the date range at the top of the page.
Sales lift shows as 0 or very low¶
Sales lift is the amount customers spend beyond the value of the gift card. If every card covers the whole order, there is nothing extra to count. This is normal for low-value orders or high-value cards.
Gift card analytics don't include my loyalty store credit¶
Loyalty store credit is reported on its own Loyalty & promotions tab of the Analytics page, not in the gift card totals. See Loyalty Analytics.
Contacting Support¶
If none of the above solves your issue, click Get help on the home page, or Contact us at the bottom of any page, and include:
- Your store domain (
.myshopify.com) - A description of what you expected vs. what happened
- The gift card's last four characters or the bulk job's link, if applicable
- A screenshot of any error messages
Response time is typically within 1 business day.