Skip to content

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:

  1. Spam/junk folder — ask the recipient to check. Gift card emails occasionally trigger spam filters, especially from shared sending domains.

  2. Email address typo — open the card in GiftCard Hero and check the recipient email. Even one wrong character means the email went elsewhere. If wrong, update it and click Resend Email.

  3. Delivery status — open the card in GiftCard Hero. Check if the email status shows "delivered," "bounced," or "pending." A bounce usually means the email address doesn't exist.

  4. Scheduled delivery — was a future delivery date set? The email won't send until that date. Check the card's scheduled send date.

  5. Custom domain — if you're using a custom sending domain, verify the DNS records are set up correctly. A misconfigured DKIM/SPF record causes silently dropped emails.

  6. Try resending — click Resend Email from the card details page. Wait 10–15 minutes and check again.

The gift card email looks broken (styling issues)

  1. The most common cause is email clients blocking external images. Ensure your logo is hosted on a reliable CDN (the app handles this automatically in the template editor).
  2. Check your email template in the preview — if it looks fine there but broken in Gmail/Outlook, the issue is client compatibility. Use the Send Test Email button to see how it renders in your own inbox.
  3. Avoid using CSS background images in the template — many email clients don't support them. Use <img> tags instead.

Variables showing as {{recipient_name}} in the email

You likely have a syntax error in your template. Check that: - Variable names match exactly (they're case-sensitive) - Opening {{ and closing }} are both present - There are no extra spaces inside the braces: {{ recipient_name }} is wrong; use {{recipient_name}}

Balance Check Widget

The widget doesn't appear on my storefront

  1. Extension not installed — go to Balance Widget in GiftCard Hero and confirm the widget is enabled. If you're using the script tag method, check that the target CSS selector exists on the page.

  2. Theme editor — if using the theme extension, open Shopify's theme editor and confirm the GiftCard Hero block is added and visible.

  3. Cache — try hard-refreshing your storefront (Ctrl+Shift+R or Cmd+Shift+R). Shopify caches theme files aggressively.

  4. Theme compatibility — very old themes (pre-2020) may not support script injection properly. Contact support if other methods don't work.

The widget shows a wrong or stale balance

The widget caches balance lookups for up to 60 seconds by default. If a customer redeems a card and immediately checks the balance, it may show the old value briefly. This resolves itself within a minute.

If balances are consistently wrong by a fixed amount, contact support — there may be a sync issue with Shopify's gift card records.

Gift Card Code Issues

"Invalid gift card code" at checkout

  1. Typo — codes are case-insensitive, but all characters must be correct. Check for 0 (zero) vs O (letter O) and 1 (one) vs I (letter I).

  2. Card disabled — the card may have been manually disabled. Check the card's status in GiftCard Hero and Shopify Admin → Gift Cards.

  3. Card expired — check the expiry date on the card. If expired, the code no longer works.

  4. Card is from another store — if the customer received the card from a different Shopify store that isn't in your Multi-Store network, it won't work at your checkout.

  5. Zero balance — a fully redeemed card with $0 balance returns "invalid" at checkout. Check the remaining balance.

A code is being rejected at POS but works online

This usually means the POS extension isn't active. Go to GiftCard Hero → POS and confirm the POS integration is enabled. Also check that the GiftCard Hero tile is installed in the POS layout.

POS Issues

The GiftCard Hero tile is missing from Shopify POS

  1. Confirm the POS extension is enabled in GiftCard Hero → POS
  2. Update the Shopify POS app to the latest version
  3. In POS, go to Settings → Apps and check that GiftCard Hero is listed and enabled
  4. Try removing and re-adding the app in Shopify POS settings
  5. On iPads: try force-closing and reopening the POS app

"Failed to load" error in the POS tile

This usually means the POS device can't reach the GiftCard Hero API. Check: - Is the device connected to the internet? - Is there a firewall or content filter blocking outbound connections? - Try switching from WiFi to cellular (or vice versa) to isolate a network issue

Bulk Operations

The bulk job is stuck at "Running"

Large jobs can take 30–60 minutes. If it's been more than 2 hours without progress: 1. Refresh the Bulk Results page 2. If still stuck, cancel the job and restart it 3. Contact support if the issue persists — include the job ID

Many rows in my bulk send are showing "Failed: invalid email"

This usually means the email column in your CSV contains extra spaces, hidden characters, or formatting issues (e.g., the email was imported from Excel with trailing spaces). Open the CSV in a text editor, not Excel, and check the raw content.

Bulk send completed but some recipients say they didn't get an email

  1. Check the results CSV — rows with "success" status were sent. Ask recipients to check spam.
  2. Check if the recipient domain has strict spam filtering (corporate emails often block bulk sends from new senders).
  3. If you're sending more than 500 emails, make sure your Shopify email sending domain's SPF/DKIM records are properly configured to improve deliverability.

Analytics

My dashboard shows $0 for all metrics

This usually means the analytics sync hasn't run yet after installation. Analytics data syncs in the background and may take up to 24 hours to populate after you install the app.

If it's been more than 24 hours: 1. Go to Dashboard → Settings and click Trigger Manual Sync 2. Wait 30 minutes and refresh

Sales lift shows as 0 or very low

Sales lift is only calculated for orders where the gift card covered less than 100% of the order total (i.e., the customer spent more than their card). If all customers are using cards that cover their entire order, lift will be low. This is normal for low-denomination cards or high-value baskets.

Contacting Support

If none of the above solves your issue, contact support with:

  • Your store domain (.myshopify.com)
  • A description of what you expected vs. what happened
  • The gift card ID or bulk job ID if applicable
  • A screenshot of any error messages

Response time is typically within 1 business day.