# GiftCard Hero — Complete Documentation This file contains the full documentation for GiftCard Hero, a Shopify app by Syncube. For the structured index, see: https://docs.syncu.be/llms.txt --- ## What is GiftCard Hero? Source: https://docs.syncu.be/giftcard-hero/getting-started/overview/ # What is GiftCard Hero? GiftCard Hero is a Shopify app that extends Shopify's built-in gift card functionality with eGift card delivery, physical gift card management, POS integration, bulk operations, and detailed analytics — everything you need to run a professional gift card program. ## What problem does it solve? Shopify's native gift cards let you issue codes and track balances, but they don't provide: - Branded email delivery when a gift card is purchased - A way for customers to buy gift cards for others directly on your storefront - Physical gift card code management - Meaningful analytics (who's buying, what's the redemption rate, unused balance) - Bulk generation and sending to lists of recipients - POS-specific tools for staff to check balances and issue cards at the counter GiftCard Hero fills these gaps while staying fully compatible with Shopify's native gift card system. ## Core features ### eGift Cards Sell digital gift cards on your storefront. Customers choose a design and denomination, fill in the recipient's name and a personal message, and the recipient gets a beautifully designed email with their code. Everything is built on Shopify's native gift card infrastructure, so balances work everywhere Shopify does. ### Physical Gift Cards Import codes from your physical card provider and manage them from one place. Sell physical cards in-store via POS or online, with the same tracking and analytics as eGift cards. ### POS Integration A dedicated Shopify POS tile lets your staff check gift card balances, issue new cards, process refunds to a gift card, and look up a customer's cards — all without leaving the POS screen. ### Bulk Operations Generate hundreds of gift card codes at once, send them to a CSV list of recipients, or update existing cards in bulk. Useful for corporate gifting, loyalty programs, and promotional campaigns. ### Analytics & Reporting Track sales, redemptions, unused balances, and sales lift — the incremental revenue that comes from customers spending more than their card value. ### Reminders Automatically email customers who haven't used their gift card balance after a set period. Recover revenue that would otherwise sit dormant. ### Reload / Top-up Let customers or your team add funds to an existing gift card — useful for store credit programs and loyalty rewards. ### Multi-store Share gift card balances across multiple Shopify stores in a network. Cards issued in one store can be redeemed in another. ## Who is it for? GiftCard Hero is designed for Shopify merchants who: - Sell in-person and online and need consistent gift card handling across both - Want to offer a polished, branded gift card experience - Run corporate gifting or bulk sales programs - Operate multiple store locations or Shopify stores - Want data on how their gift card program is performing ## How it works with Shopify GiftCard Hero does not replace Shopify's gift card system — it extends it. All gift cards are stored in your Shopify admin and appear in your Shopify financial reports. The app adds a layer on top: branded delivery, a better storefront experience, analytics, and operational tools. > **Note:** GiftCard Hero requires a Shopify plan that includes gift card support (Shopify, Advanced, or Plus). The Basic plan does not include native gift card functionality. --- ## Installation & Setup Source: https://docs.syncu.be/giftcard-hero/getting-started/installation/ # Installation & Setup ## Requirements Before installing, make sure your store meets these requirements: - **Shopify plan:** Shopify, Advanced Shopify, or Shopify Plus (gift cards are not available on Basic) - **Store currency:** Set to your primary operating currency — GiftCard Hero uses this for gift card denominations - **Admin access:** You need the "Manage gift cards" permission in Shopify Admin ## Installing the app 1. Find GiftCard Hero in the [Shopify App Store](https://apps.shopify.com). 2. Click **Add app**. 3. Review the permissions the app requests and click **Install app**. ### Permissions explained GiftCard Hero requests access to: | Permission | Why it's needed | |------------|----------------| | Gift cards (read/write) | Create, update, and read gift card balances | | Orders (read) | Match gift card purchases to orders for analytics | | Customers (read/write) | Associate gift cards with customer accounts | | Products (read/write) | Set up the gift card product on your storefront | | Storefront API | Enable customer-facing features | ## Completing the onboarding wizard After installation, you'll be taken through the setup wizard. It covers the essential steps: ### Step 1 — Select a plan Choose the GiftCard Hero subscription plan that fits your store's volume. You can upgrade or downgrade later from the billing section. ### Step 2 — Set up your eGift card product The wizard creates a Shopify product that customers use to purchase gift cards. You can: - Set the product title and description - Choose which denominations to offer (e.g., $25, $50, $100) - Allow custom amounts within a range This product will appear in your Shopify storefront and can be managed like any other product. ### Step 3 — Customize the gift card email Set up the email that recipients receive with their gift card code. At minimum, configure: - Your store logo - A message from the store You can fully customize the template later from [[email-templates|Email Templates]]. ### Step 4 — Enable the balance check widget (optional) If you want customers to check their gift card balance on your storefront, enable the widget here. It adds a small widget to your storefront that you can position and style. Full configuration is available in [[balance-widget|Balance Widget]]. ### Step 5 — POS setup (optional) If you use Shopify POS, follow the prompts to enable the GiftCard Hero POS tile. See [[pos-integration|POS Integration]] for the full setup guide. ## After installation Once the wizard is complete, you'll land on the GiftCard Hero dashboard. At this point: - Your eGift card product is live on your storefront - Customers can purchase gift cards and recipients will receive them by email - You can access all features from the left navigation ## Uninstalling If you uninstall GiftCard Hero: - All existing gift cards remain valid in your Shopify store — they are native Shopify gift cards - The balance check widget is removed from your storefront - Your customizations and analytics history are retained for 30 days in case you reinstall - After 30 days, your data is permanently deleted per our data retention policy - Greeting messages/videos become unavailable > **Note:** Uninstalling does not delete or invalidate any gift cards that have already been issued. Customers can still redeem them at checkout. --- ## Quick Start: Send Your First Gift Card Source: https://docs.syncu.be/giftcard-hero/getting-started/quick-start/ # Quick Start: Send Your First Gift Card This guide walks you through manually issuing one eGift card. It takes about 5 minutes and is the fastest way to see GiftCard Hero in action. > If you want customers to purchase gift cards themselves from your storefront, this still works — but that flow is automatic once your store is set up. This guide is for manually issuing a card (e.g., as a gift to a VIP customer). ## Step 1 — Go to eGift Cards In GiftCard Hero, click **eGift Cards** in the left navigation. You'll see your list of gift card types (denominations and designs). If you just installed the app, there may already be default denominations set up from the onboarding wizard. ## Step 2 — Click "Issue Gift Card" Click the **Issue Gift Card** button in the top right corner. ## Step 3 — Fill in the details | Field | What to enter | |-------|--------------| | **Amount** | The value to load onto the card (e.g., 50) | | **Recipient email** | Where the gift card email will be sent | | **Recipient name** | Displayed in the email greeting | | **Sender name** | Shown as the "from" in the email | | **Personal message** | Optional message included in the email | | **Send date** | Send now, or schedule for a future date | ## Step 4 — Click "Send" Click **Send Gift Card**. The recipient will receive an email within a few seconds containing: - The gift card code - The current balance - A link to check their balance at any time - Your personal message ## Step 5 — Verify in Shopify Admin To confirm everything worked: 1. Go to your **Shopify Admin → Gift Cards** 2. You'll see the new card with its balance and the last 4 digits of the code The card is now a fully functional Shopify gift card. The recipient can use the code at your store's checkout. ## What happens when the recipient uses it 1. Recipient goes to your store and adds items to their cart 2. At checkout, they enter their gift card code in the **Gift card or discount code** field 3. Shopify applies the balance to the order 4. If the order total exceeds the card balance, they pay the remainder with another method 5. The remaining balance stays on the card for future purchases ## Next steps - [[egift-cards|Set up gift card types and designs]] for your storefront - [[email-templates|Customize the gift card email template]] - [[bulk-operations|Send gift cards in bulk]] to a list of recipients - [[pos-integration|Set up POS]] so staff can issue and check cards in-store --- ## How to Test a Gift Card Source: https://docs.syncu.be/giftcard-hero/getting-started/testing/ # How to Test a Gift Card Test how gift cards work in your store without making an actual payment. ## 1. Create a test discount - In Shopify admin, go to **Discounts → Create discount** - Choose **Amount off products** - Set value to cover full price (e.g., 100%) ## 2. Select the gift card product - Under **Applies to**, choose **Specific products** - Select your Gift Card product ## 3. Complete a test purchase - Go to your storefront, add the gift card to cart, apply the discount code - Total becomes $0, complete checkout without payment ## 4. Test the gift card - Check email for the issued gift card - Use the code during checkout to confirm it works ## 5. Clean up - Return to Discounts in Shopify admin - Deactivate or delete the test discount > **Tip:** This method ensures you can fully test the gift card purchase and redemption process without charging your store's payment method. --- ## How Gift Cards Work in Shopify Source: https://docs.syncu.be/giftcard-hero/getting-started/shopify-gift-cards-101/ # How Gift Cards Work in Shopify Before configuring GiftCard Hero, it helps to understand how Shopify handles gift cards natively. This article explains the underlying mechanics so you know what the app is building on. ## What a Shopify gift card is A Shopify gift card is a stored-value record in your store's database. It has: - A unique **code** (typically 16 alphanumeric characters split into groups, e.g. `ABCD-EFGH-IJKL-MNOP`) - A **balance** in your store's currency - An optional **expiry date** - A **status** (active, disabled, or fully redeemed) - An optional association with a **customer account** When a customer checks out with a gift card code, Shopify deducts the amount from the card's balance and records the transaction. If the order total exceeds the card balance, the customer pays the remainder with another payment method. ## Shopify plan requirements Gift cards are only available on **Shopify, Advanced Shopify, and Shopify Plus** plans. The Basic Shopify plan does not support gift cards. If you're on Basic, you'll need to upgrade before using GiftCard Hero. ## How gift cards are created in Shopify There are two ways to create a gift card natively: 1. **Shopify Admin → Gift Cards → Issue gift card** — manually create one for a specific amount and optionally assign it to a customer. 2. **A customer purchases a gift card product** — when your store sells a gift card product, Shopify automatically generates a code and emails it to the buyer. GiftCard Hero uses both mechanisms behind the scenes, and adds a third: **bulk generation** via the Shopify Admin API. ## Gift cards as a payment method Gift cards in Shopify are a **payment method**, not a discount. This is an important distinction: | Gift cards | Discount codes | |------------|---------------| | Reduce the order total as a payment | Reduce the price of items | | Balance persists across orders | Single use | | Appear in financial reports as liability | Appear as a discount | | Can be combined with discounts | Cannot usually be combined with other discounts | | Not taxed when purchased (in most regions) | N/A | ## Taxes and accounting In most jurisdictions, gift card **purchases** are not taxable — you're selling a future payment instrument, not a product. The tax is collected when the gift card is **redeemed** to buy taxable goods. Shopify handles this automatically: gift card sales are recorded as a liability, and when redeemed, the liability is offset against the sale. > **Important:** Tax laws vary by country and state. Always consult your accountant for your specific situation. Some US states (e.g., California) have specific gift card regulations. ## Expiry dates Shopify allows you to set an expiry date on a gift card, but **you must comply with local law**: - **United States:** Most states prohibit expiry dates shorter than 5 years. California, Florida, and others ban expiry dates entirely on gift cards under a certain value. - **European Union:** No general EU-wide ban, but member states have their own rules. - **Canada:** Gift cards cannot expire under federal law (with some exceptions). - **Australia:** Gift cards must have at least a 3-year expiry under Australian Consumer Law. GiftCard Hero lets you set expiry globally or per gift card type. The app does not enforce legal compliance automatically — you are responsible for setting appropriate expiry dates for your region. ## What Shopify does NOT provide natively | Feature | Native Shopify | With GiftCard Hero | |---------|---------------|-------------------| | Branded email with gift card code | Basic email only | Fully customizable | | Recipient can personalize (message, design) | No | Yes | | Physical gift card code management | No | Yes | | Balance check widget on storefront | No | Yes | | Bulk generation and sending | No | Yes | | Analytics (redemption rate, sales lift) | Basic | Detailed | | POS tools (balance check, issue, refund) | No | Yes | | Unused balance reminders | No | Yes | | Multi-store shared balances | No | Yes | ## How GiftCard Hero fits in GiftCard Hero is a **layer on top of Shopify's gift card system**. It uses the Shopify Admin API to: - Create gift cards on your behalf when orders are placed or bulk jobs run - Read card balances for the balance check widget and POS tools - Update card balances during top-ups - Pull transaction data for analytics All gift cards created by GiftCard Hero appear in your Shopify Admin under **Gift Cards** — they are full Shopify gift cards. ## Key limitations to be aware of - Gift cards cannot be applied to orders with subscriptions in some configurations. - Gift cards cannot be used to pay for other gift cards (Shopify restriction). - One Shopify order can have up to 10 gift cards applied to it. - Gift card codes are case-insensitive in Shopify's checkout. - Shopify does not expose the full 16-character code via API after creation for security reasons — GiftCard Hero stores a masked version and the last 4 digits. --- ## eGift Cards & Physical Gift Cards Source: https://docs.syncu.be/giftcard-hero/features/egift-cards/ # eGift Cards & Physical Gift Cards The Gift Cards page is the main configuration area for both digital (eGift) and physical gift cards. Go to **eGift Cards** in the left navigation. The page has two tabs: **E-Gift cards** and **Physical gift cards**. --- ## E-Gift Cards tab ### Enable / disable Toggle eGift cards on or off. When disabled, the storefront gift card widget and purchase flow are hidden from customers. ### Card designs A grid of available design thumbnails. Click a design to select it as the active design for gift cards. The selected design appears in the gift card delivery email and on the gift card page. To upload a custom design image, click **Upload custom card**. The image is added to the grid immediately. ### Card categories Organize designs into named groups that customers see on the gift card selection page. Manage categories via the **Organize** button, which takes you to [[card-categories|Card Categories]]. ### Custom amount Allow customers to enter any amount instead of (or in addition to) fixed denominations. - **Enable custom amount** — toggle on to allow buyer-specified amounts - **Custom amount expiration** — optionally set an expiry for cards issued with a custom amount **About the helper product:** when Custom Amount is enabled, GiftCard Hero automatically creates a helper product in your Shopify catalog (with a small placeholder price like $0.01). Shopify's checkout requires a real product/variant in the cart, so the app puts this helper product there and dynamically rewrites the line item price at checkout to the exact amount the customer entered. If you see this product appear in your inventory: - **Don't delete it** while Custom Amount is enabled - removing it breaks the feature. - **Don't edit its title, price, or variants** manually - the app manages it. - To hide it from the storefront, simply **unlist it from the Online Store sales channel** (Product → Sales channels → uncheck Online Store). It will no longer appear in collections, search, or via direct URL, while continuing to work for Custom Amount. - If you turn Custom Amount off later, the helper product can be removed - reach out to support and we'll clean it up for you. ### Gift card product Link the gift card product from your Shopify catalog. GiftCard Hero uses this product to trigger gift card creation when an order is placed. You can also configure **one-time purchase products** — products that issue a gift card only once per customer. ### Automation settings | Option | What it does | |--------|--------------| | **Auto-disable on refund** | Automatically disable a gift card when its order is refunded | | **Fulfill orders on order creation** | Mark the gift card line item as fulfilled immediately when the order is created | ### Email copy Enter an admin email address to receive a BCC of every gift card delivery email. Useful for quality control or record-keeping. ### Save codes When enabled, gift card codes are saved in the order notes for easy reference. --- ## Detailed eGift Card Settings These options are available in the eGift Cards configuration: | Setting | Description | |---------|-------------| | **Allow Scheduled Send** | Customers can schedule delivery on a specific date | | **Allow Video Messages** | Customers can attach video messages (up to 2 minutes, stored 60 days) | | **Allow Custom Amount** | Custom values via draft order with separate checkout | | **Custom Amount Item SKU** | Define SKU for custom-amount gift cards | | **Custom Amount Limits** | Set min/max values for custom amounts | | **Use Gift Card Product Images** | Use uploaded product images as designs (for multiple gift card products) | | **Lock Design for Variant** | Restrict designs to specific variants, auto-switching on selection | | **Show Recipient's Name Field** | Adds name field on physical card and email | | **Set "Send to Me" as Default** | Default tab delivers to checkout email instead of gift recipient | | **Custom "Start Shopping" Link** | Replace homepage link on gift card page with custom URL | | **Replace POS QR with Shop Link** | Swap POS QR code for store link (for printed vouchers) | | **Hide Gift Cards in Account** | Remove auto-generated "My Gift Cards" from customer portal | | **Show Balance Check in Account** | Display balance widget in "My Gift Cards" page | | **Disable Page Animation** | Turn off envelope animation on gift card page | | **Force One-Time Use** | Reset remaining balance to zero after first purchase | ### Custom eGift Card Designs Upload your own designs in JPG, PNG, GIF, SVG, or WEBP formats. Recommended dimensions: 450px x 270px. --- ## Physical Gift Cards tab Controls physical card code import and management. See [[physical-cards|Physical Gift Cards]] for the full import and inventory workflow. | Option | What it does | |--------|--------------| | **Enable physical gift cards** | Toggle to activate the physical card feature | | **Add physical codes** | Open the import modal to upload card codes via CSV | | **Email copy** | Admin email to receive a BCC of physical card emails | | **Auto-disable on refund** | Disable a physical card code when its order is refunded | --- ## Header actions These buttons appear at the top of the page: | Button | Where it goes | |--------|---------------| | **Issue e-Gift card** | Opens the manual card issuance form (see below) | | **Order physical gift cards** | Link to Shopify's hardware store to order physical cards | | **Translations** | Opens [[card-design|Design & Translations]] to customize language strings | --- ## Issuing a gift card manually To send a single gift card directly to a customer — for example, as a goodwill gesture or compensation: 1. Click **Issue e-Gift card** in the page header 2. Fill in the form: | Field | Notes | |-------|-------| | **Initial value** | Amount in your store's currency | | **Message** | Optional personal message (up to 200 characters) | | **From** | Sender name shown in the email (up to 40 characters) | | **Gift code** | Leave blank to auto-generate, or enter a custom code (8–18 characters) | | **Card design** | Select from the available design thumbnails | | **Recipient email** | Where the gift card email is sent | | **Recipient name** | Shown in the email greeting | | **Send date / time** | Schedule delivery for a future date, or leave blank to send immediately | | **Notes** | Internal note — not visible to the recipient | 3. Click **Send gift card** The card is created in Shopify and the delivery email is sent to the recipient on the scheduled date and time. --- ## Advanced Settings Go to **eGift Cards → Advanced Settings** for additional technical options. ### Regular products as gift cards Select any Shopify products to behave as gift cards. When one of these products is purchased, GiftCard Hero generates a gift card code instead of fulfilling a physical item. ### Variant selection types - **All Variants (Blue Badge):** The entire product triggers gift card creation - **Partial Variants (Orange Badge):** Only specific variants trigger it, showing "X of Y variants selected" For each selected product you can configure: | Option | Description | |--------|-------------| | **Skip gift codes generation** | Don't generate a Shopify gift card code — use this if you manage codes externally | | **Save gift codes in order notes** | Include the generated code in the Shopify order notes | | **Don't send gift card email to purchaser** | Suppress the confirmation email to the buyer | | **Don't mark item as fulfilled** | Keep the line item unfulfilled after gift card issuance | | **Track inventory for variants** | Enable Shopify inventory tracking on the product's variants | ### Predefined gift codes Upload a list of pre-made codes. GiftCard Hero assigns them to orders in sequence, instead of generating random codes. This is useful when codes are pre-printed on physical cards. 1. Select the product and variant these codes belong to 2. Paste codes into the text area (one per line) 3. Click **Submit codes** The code table shows each uploaded code with its status (unused / used), registration date, and the order it was assigned to. --- ## How it looks on your storefront --- ## Design & Translations Source: https://docs.syncu.be/giftcard-hero/features/card-design/ # Design & Translations The Design & Translations page lets you customize the text labels used in GiftCard Hero's storefront components — the gift card page, delivery emails, and the balance check widget. Go to **eGift Cards → Translations** (click the **Translations** button on the Gift Cards page). --- ## Language selection Use the language dropdown to select the language you want to configure. The list contains 80+ languages. When a customer visits your store, GiftCard Hero uses the Shopify locale associated with their session to pick the right translation. If no translation exists for their locale, the default English text is shown. --- ## Translation fields After selecting a language, a set of editable text fields appears. Each field corresponds to a label, message, or button shown in the gift card UI. Fill in the translated text for each field you want to customize. What you can translate includes: - Gift card page heading and description text - Button labels (e.g., "Send gift card", "Check balance") - Remaining balance label - Expiry date label - Email subjects and body text fragments - Error messages (invalid code, card expired, etc.) - Confirmation and success messages --- ## Saving Click **Save** to apply your changes. Click **Discard** to revert any unsaved edits. Changes take effect immediately for new sessions. Customers already on the page may need to refresh to see updated text. --- ## Card design images Card design images — the visual appearance of the gift card in emails and on the storefront — are managed on the main [[egift-cards|eGift Cards]] page, not here. On that page you can: - Select from built-in design thumbnails - Upload a custom design image The Design & Translations page handles **language/text customization only**. --- ## Card Categories & Organization Source: https://docs.syncu.be/giftcard-hero/features/card-categories/ # Card Categories & Organization The Organize page lets you group gift card designs into named categories, assign designs to those categories, and control the display order. Go to **eGift Cards → Organize** (click the **Organize** button on the Gift Cards page). --- ## Creating a category 1. Click **Add category** (a popover opens) 2. Enter a category name 3. Confirm The category appears as a collapsible section on the Organize page. --- ## Assigning designs to a category 1. Expand a category section (click its header) 2. Click **Add gift cards to the category** inside the section 3. Select the designs to add from the picker 4. The selected designs appear as thumbnails inside the category To remove a design from a category, click its thumbnail in the category section. --- ## Display order Within a category, the order of the card thumbnails controls the order they appear to customers. Reorder them by rearranging them in the category. --- ## Removing a category Click **Remove** (the destructive action on each category section) to delete the category. The designs in that category are not deleted — they become uncategorized. --- ## Saving Click **Save** to apply all changes (category additions, design assignments, and order changes). --- ## How categories appear on your storefront The categories and their assigned designs are shown to customers on your gift card selection page. Customers can browse by category to find designs for their occasion (e.g., birthday, holiday, corporate). If no categories are set up, all designs are shown in a single flat list. --- ## Physical Gift Cards Source: https://docs.syncu.be/giftcard-hero/features/physical-cards/ # Physical Gift Cards Physical gift cards are pre-printed cards sold in-store or included in orders. GiftCard Hero lets you import the codes printed on your cards, load them into Shopify as active gift cards, and track their usage. ## How physical cards work Physical gift cards come from a card manufacturer with a unique code printed or embossed on each card. The workflow is: 1. **Order cards** from your manufacturer (they provide a file with the codes) 2. **Import codes** into GiftCard Hero 3. **Load balances** — each code becomes an active Shopify gift card with a set balance 4. **Sell cards** in-store via POS or online 5. **Track usage** — redemptions appear in your analytics alongside eGift cards ## Importing codes ### Preparing your code file GiftCard Hero accepts a CSV file with one code per row. The file should have a column for the gift card code. If your manufacturer provides a different format, you can remap columns during the import. Example CSV: ``` code ABCD-1234-EFGH-5678 IJKL-9012-MNOP-3456 QRST-7890-UVWX-1234 ``` ### Running the import 1. Go to **eGift Cards** → **Physical Cards** tab 2. Click **Import Codes** 3. Upload your CSV file 4. Map the code column if needed 5. Set the **initial balance** for all imported cards 6. Set an optional expiry date 7. Click **Import** GiftCard Hero creates a Shopify gift card for each code. This may take a few minutes if you're importing thousands of codes. ### Import limits A single import batch supports up to 10,000 codes. For larger batches, split your file and run multiple imports. ## Managing physical card inventory The Physical Cards tab shows: - Total codes imported - Cards sold (codes that have been activated at checkout) - Cards with remaining balance - Fully redeemed cards ### Activating cards Physical cards can be **pre-loaded** (the code is active with a balance as soon as it's imported) or **activated on sale** (the balance is loaded when the card is sold at checkout or POS). - **Pre-loaded:** customers buy the card and the code on it already has value. Common for cards in display stands. - **Activated on sale:** the card is worthless until it's scanned at the register. More secure for high-value cards. Configure this in **Physical Cards → Settings** before importing. ## Selling physical cards ### At POS When a customer buys a physical gift card at your POS terminal, your staff can: 1. Scan or type the code from the back of the card 2. Confirm the balance was loaded correctly 3. Hand the card to the customer See [[pos-integration|POS Integration]] for the full POS flow. ### Online You can list physical gift cards as a product in your Shopify store. When purchased, the customer receives an email with the pre-assigned code from your inventory. ## Tracking physical card redemptions All redemptions (whether in POS or online) appear in GiftCard Hero's analytics and in Shopify Admin under the gift card's transaction history. You can see: - Which cards have been sold and activated - Current remaining balances - Which store location processed each transaction (for multi-location stores) ## Common scenarios ### Card codes are being rejected at checkout **Check:** 1. Was the import completed successfully? Look for any errors in the import history. 2. Is the card's balance greater than $0? 3. Has the card expired? 4. Is the code formatted correctly? Shopify codes are case-insensitive but must match the imported format. ### A customer lost their physical card Physical card codes cannot be replaced automatically — the code is the card. If a customer loses their card, you can: 1. Look up the code in your records 2. Check the remaining balance in GiftCard Hero 3. Manually issue a new eGift card for the remaining balance as a goodwill gesture 4. Disable the old code to prevent misuse See also: [[physical-card-inventory|Managing Physical Gift Card Inventory]] for a full operational guide. --- ## Where to Purchase Physical Gift Cards Physical gift cards can be purchased from [Shopify Customizable Gift Cards](https://www.shopify.com/pos/store/collections/customizable-gift-cards). --- ## Using a Third-Party Printing Company 1. In Gift Card Hero, go to **Bulk Tools** 2. Select **Generate without import** (creates inactive codes until sold) 3. Set number of codes and click Generate 4. Download CSV with 16-character codes and QR code strings Provide the CSV to your printing company. --- ## Registering Physical Gift Codes Two methods: Auto Assignment and Manual Assignment. ### Auto Assignment Automatic registration as codes are generated. Gift cards are assigned and balances loaded automatically. **Cons:** Cards are assigned one by one. See [Gift Codes Auto-Assignment](#gift-codes-auto-assignment) section below. ### Manual Assignment 1. Navigate to **Admin → Orders** → find the order with a physical gift card 2. Scroll to **App blocks** → click **+ App block** 3. Select **Gift Card Hero Admin** 4. **Pin** the extension for easy future access --- ## Scanning QR Codes 1. Click the **Scan QR** button (opens a new page) 2. Session is active for 10 minutes with a progress timer 3. Click **Request Camera Permissions** → Allow 4. Press **Start Scanning** 5. Align the QR code in the scanning rectangle 6. A success message appears → close the window 7. Code info is visible in the App Admin extension block --- ## Gift Codes Auto-Assignment Upload batches of gift codes for automatic order assignment. Upon purchase, the system selects a code from the pool and loads the balance. **Toggle:** Enable or disable auto-assignment. **Generate new code on sale:** Creates codes dynamically when inventory runs out. When enabled, store owners write codes on blank cards. Not suitable for preprinted cards. **Upload codes:** Enter codes in the text area, separated by newlines or commas. Requirements: 8-18 characters, alphanumeric only. **Status tracking:** - **Assigned** — linked to an order - **Unused** — available in the pool - **With errors** — upload or assignment failures --- ## Physical Gift Card Configuration After enabling physical gift cards, click **Configure physical gift product** to access these options: | Setting | Description | |---------|-------------| | **Disable gift card greeting message** | Removes the customer's ability to add messages | | **Duplicate gift card details in additional notes** | Copies data to order notes for ERP systems | | **Show delivery address fields** | Allows separate shipping address entry | | **Custom amount** | Permits customer-defined denominations (with configurable min/max limits, SKU: `physical-custom-amount`) | --- ## Additional charge You can add a fixed extra charge to physical gift cards — for example a delivery fee, an envelope or gift-wrapping fee, or a fee for adding a personal gift message. The charge is added automatically in the cart (via a Shopify cart transform) and is shown to the customer in the cart and on checkout. Find these options on the **eGift Cards → Physical Cards** tab, in the **Additional charge** section. ### Setting it up 1. Enable **Add additional charge**. 2. Choose **When to apply**: - **Only when the card is personalized** — the charge is added when the customer fills in a gift message, a recipient, or a sender. Cards with no personalization are not charged. - **Always for physical gift cards** — the charge is added to every physical gift card. 3. Set the **Charge amount** in your store's primary currency. 4. Enter a **Charge name** for each language your store publishes (see below). 5. Save your settings. The first time you enable the charge, GiftCard Hero sets up a hidden fee product and registers the cart transform automatically — this can take a moment. ### Translating the charge name The charge name is visible to customers, so you can translate it into every language your store publishes: 1. Pick a language from the **Language** dropdown. 2. Enter the **Charge name** for that language (for example "Gift wrapping" / "Geschenkverpackung"). The name in your **primary language is required**. Any language you leave empty falls back to the primary-language name. The translated name appears both in the storefront gift card widget and on the native Shopify checkout. ### Notes - The charge applies to **physical** gift cards only, not eGift cards, and one charge is added per physical gift card line. - The amount is set in your store's primary currency. - If you disable the greeting message for physical cards **and** use the "Only when personalized" mode, the charge still applies when a recipient or sender is entered. If your cards have no personalization fields at all, switch to **Always** instead — the app shows a warning when this combination would never charge. --- ## Gift Card Admin Block Source: https://docs.syncu.be/giftcard-hero/features/admin-block/ # Gift Card Admin Block The Gift Card Hero admin block adds management features directly to Shopify's gift card detail page. ## Adding the block 1. Navigate to **Products → Gift cards** in Shopify admin 2. Select a gift card to open the detail view 3. In the **Blocks** section, click **Customize** 4. Find **Gift Card Hero** in the available blocks list 5. Click **Add block** and optionally **Pin** it for all staff 6. Save changes ## Using the block The management panel provides: - **Send the gift card** to customer, recipient, or admin via dropdown - **View the timeline** of all actions for this gift card - **Add internal comments** for staff (not visible to customers) ## Notes - Ensure correct email address before sending - Recipient option may be disabled if no recipient was specified originally - All comments and history are staff-only --- ## Resending or Editing a Gift Card Source: https://docs.syncu.be/giftcard-hero/features/resend-edit/ # Resending or Editing a Gift Card ## Resending from Shopify Admin 1. Go to **Products → Gift cards** 2. Click the gift card code you want to resend 3. In the top right, click **Resend gift card** 4. Shopify sends the original email again to the recipient > **Note:** You can only resend to the originally entered email. To change the email, use the Queue Report method below. ## Changing email, delivery date, or canceling 1. Go to **Apps → Gift Card Hero → Analytics → Queue Report** 2. Find the gift card and click on the **email link** 3. In the popover, you can: - Change the recipient email address - Adjust the delivery date - Remove the gift card from the queue --- ## Dashboard & Analytics Source: https://docs.syncu.be/giftcard-hero/features/dashboard/ # Dashboard & Analytics The GiftCard Hero analytics dashboard gives you a view of how your gift card program is performing. Go to **Analytics** in the left navigation. --- ## Date range Use the **date range picker** at the top of the dashboard to set the reporting period. Select start and end dates to see metrics for any time window. --- ## Key metrics ### Gift cards queue Shows pending and sent gift cards — cards that are in flight or recently issued. ### Redemption revenue Total value of gift cards applied at checkout during the selected period. This is the actual revenue attributed to gift cards being spent. ### Sales lift / Overspend The extra revenue generated because customers spent more than their gift card value. For example, if a customer has a $50 card and spends $78, the lift is $28. Sales lift is a key metric showing the real economic value of your gift card program — it measures revenue beyond the face value of cards sold. ### Unused vs. used balance A donut chart showing the proportion of total issued value that has been redeemed versus still outstanding. ### Redeemed gift cards count Number of gift cards that have been at least partially redeemed in the selected period. ### Orders paid with gift cards A detailed list of orders where a gift card was used as payment, including customer information and order links (opens in Shopify Admin). ### Unused balance reminders Count of reminder emails sent and scheduled in the selected period. See [[reminders|Unused Balance Reminders]] for configuration. ### Average gift balance value per order The average remaining balance on gift cards applied to orders — useful for understanding how much of the card value customers typically use in one transaction. ### Redemptions amount (daily) A daily breakdown of redemption amounts over the selected period. ### Gift Card Transactions report A detailed transaction-level report (requires the `read_all_orders` scope). If this scope isn't granted, a prompt appears to enable it. --- ## Data sync GiftCard Hero syncs analytics data from Shopify in the background. The sync status is shown as a progress banner when a sync is in progress. ### Triggering a sync Click the **Sync Data** button to manually trigger a sync. Options: - **Sync for period** — syncs data for the selected date range only - **Sync for all time** — syncs all historical data from the beginning (use this after first install or if data looks incomplete) Sync progress is shown as a percentage. You can leave the page — sync continues in the background. ### First install After installing GiftCard Hero, the dashboard may show $0 for all metrics until the initial sync completes. The all-time sync can take up to 24 hours for stores with large order history. --- ## Full Report Click **View Report** next to any metric to open the detailed report page for that section. The full report includes transaction-level data and can be filtered by date. --- ## Understanding your numbers ### Dashboard shows $0 after install The analytics sync hasn't run yet. Click **Sync Data → Sync for all time** and wait for the sync to complete (up to 24 hours for large stores). ### Sales lift shows 0 or very low Sales lift is only calculated for orders where the gift card covered less than 100% of the order total. If all customers are using cards that cover the entire order (e.g., a $25 card on a $25 order), lift will be zero. This is normal for low-denomination cards or high-value baskets. ### Redemption revenue doesn't match Shopify's reports GiftCard Hero syncs data from Shopify's API. Minor differences can occur due to sync timing or orders that were edited after being placed. Run a manual sync to refresh. --- ## Bulk Operations Source: https://docs.syncu.be/giftcard-hero/features/bulk-operations/ # Bulk Operations Bulk operations let you create and distribute large numbers of gift cards in one job — without issuing them one at a time. ## Three types of bulk jobs | Job type | What it does | Best for | |----------|-------------|----------| | **Generate** | Creates codes with a set balance, no recipient | Export to CSV, physical card programs, internal use | | **Send** | Creates codes and emails each one to a recipient | Corporate gifting, loyalty rewards, promotions | | **Update** | Adjusts the balance on a set of existing cards | Adding bonus credit, correcting balances | ## Bulk Generate Use this to create a batch of gift card codes that you'll distribute yourself (e.g., export and print, add to packaging, hand to a partner). ### Settings | Field | Description | |-------|-------------| | **Quantity** | Number of cards to generate (up to 10,000 per job) | | **Amount per card** | Fixed balance loaded on each card | | **Expiry** | Optional expiry date | | **Gift card type** | Which design/settings template to use | | **Export format** | CSV with code, balance, expiry, and status | ### Generate without import Use the **Generate without import** option for physical printed cards. This generates codes without activating them in Shopify — codes remain inactive until sold. Configure a prefix (up to 4 characters) and code length (8-16 characters). ### After generation When the job completes, you can download a CSV with all generated codes and their details. The codes are also live in Shopify as active gift cards (unless you used "Generate without import"). ## Bulk Send Use this to send gift cards to a list of named recipients. Each person gets their own card and a personalized email. ### Preparing your recipient list Upload a CSV with the following columns: | Column | Required | Description | |--------|----------|-------------| | `initial_value` | Yes | Amount in your store's currency | | `email` | Yes | Recipient's email address | | `name` | Optional | Recipient name, used in email greeting | | `message` | Optional | Per-recipient personal message | | `expires_on` | Optional | Expiry date in `YYYY-MM-DD` format | Example CSV: ``` initial_value,email,name,message,expires_on 50,jane@example.com,Jane Smith,Thank you for your loyalty!,2027-03-15 100,bob@example.com,Bob Jones,Happy birthday Bob!, ``` ### Settings - **Default amount** — used for rows that don't specify an amount - **Gift card type** — design and settings template - **Sender name** — shown in the email as "A gift from..." - **Default message** — used when a row doesn't have a message column - **Schedule** — send all at once or spread over time (e.g., 500/hour to avoid email throttling) ### Sending throttle For large lists (1,000+), GiftCard Hero spreads the sends over time to avoid hitting Shopify's email rate limits. You can set the rate in the advanced options. ## Bulk Update Adjust balances on a set of existing cards. Use cases: - Add $10 bonus credit to all cards issued in a specific month - Zero out cards that are past expiry - Correct an incorrect balance after a system issue Upload a CSV with the following columns: | Column | Required | Description | |--------|----------|-------------| | `code` | Yes | The gift card code to update | | `new_balance` | Optional | New balance value. Use `+` or `-` prefix for relative adjustments (e.g., `+10.00` adds $10, `-5.00` subtracts $5) | | `disabled` | Optional | Set to `TRUE` to disable the card (irreversible) | | `recipient_email` | Optional | Update the recipient email | | `customer_email` | Optional | Update the customer email | | `notify_customer` | Optional | Send notification to customer | | `notify_recipient` | Optional | Send notification to recipient | ``` code,new_balance ABCD-1234-EFGH-5678,75.00 IJKL-9012-MNOP-3456,+10.00 QRST-7890-UVWX-1234,-5.00 ``` > **Note:** Bulk Update sets the balance to the value you provide — it doesn't add or subtract — unless you use the `+` or `-` prefix for relative adjustments. To add $10 to a card with $40, either set `new_balance` to `50.00` or use `+10.00`. ## Bulk Import Import existing gift cards from other systems into GiftCard Hero. Upload a CSV with the following columns: | Column | Required | Description | |--------|----------|-------------| | `initial_value` | Yes | Amount in your store's currency | | `code` | Optional | Gift card code (auto-generated if omitted) | | `customer_id` | Optional | Shopify customer ID to associate | | `expires_on` | Optional | Expiry date in `YYYY-MM-DD` format | | `recipient_email` | Optional | Recipient's email address | | `customer_email` | Optional | Customer's email address | | `notify_customer` | Optional | Send notification to customer | | `notify_recipient` | Optional | Send notification to recipient | ### Steps 1. Navigate to the **Import** tab 2. Prepare your CSV file with the columns above 3. Upload the CSV file 4. Click **Start Import** --- ## Tracking results After starting any bulk job, you can monitor progress in **Bulk → Results**. The results page shows: - Job status (queued, running, completed, failed) - Progress (e.g., 847 / 1000 sent) - Per-row errors (e.g., invalid email, duplicate code) - Download links for the results CSV ### Results CSV The results CSV includes all input columns plus: - `status` — success / failed / skipped - `error` — error message if failed - `helpscout_url` — public URL of the gift card (for Generate jobs) - `code_last4` — last 4 digits of the gift card code ## Limits and performance | Limit | Value | |-------|-------| | Max cards per Generate job | 10,000 | | Max rows per Send job | 10,000 | | Max rows per Update job | 50,000 | | Estimated speed (Generate) | ~500 cards/minute | | Estimated speed (Send) | ~200 emails/minute | Large jobs run in the background — you don't need to keep the browser open. You'll receive a summary email when the job completes. --- ## Managing Gift Cards with Bulk Actions Source: https://docs.syncu.be/giftcard-hero/features/managing-gift-cards-with-bulk-actions/ # 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 by uploading a single file. 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. From your main dashboard, navigate to the **Gift Cards** section. 2. Click on the **Bulk Actions** tab or menu item. You will see a page with several tabs: **Generate**, **Send**, **Update**, **Import**, and **Results**. Each tab corresponds to a specific bulk action you can perform. ## Preparing Your Data File All bulk operations are performed by uploading a CSV (Comma-Separated Values) file. 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`). - Each subsequent row represents one gift card to be processed. - We recommend downloading our template file 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. --- ## 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 will be available in your system to be used or sent later. **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`). - **Number of gift cards** — Specify how many cards you want to create with these settings. - **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). - **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. Click the **Start generation** button. The system will then create the specified number of gift cards with these settings. You can view the results and download a CSV file with results of this job on the **Results** tab. **Special option: Generate without import** Check the **Generate without import** box if you plan to use these gift card codes for physical, printed cards. When this option is selected, the codes are generated but are not activated in the system immediately. --- ## 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. **Required & optional fields:** | Field Name | Required | Description | |------------|----------|-------------| | `initial_value` | Yes | The starting balance of the gift card. | | `email` | Yes | The email address of the person receiving the gift card. | | `name` | No | The recipient's name, which can be used in the email template. | | `message` | No | A personal message to include in the gift card email. | | `expires_on` | No | The date the gift card expires, in `YYYY-MM-DD` format. | > **Note:** If a `recipient_email` is provided, the system will automatically be set to notify the recipient. Similarly, if a `customer_email` is provided, the purchaser will be notified. **How to send gift cards:** 1. Navigate to the **Send** tab. 2. Prepare your CSV file with the required columns. Ensure all email addresses are correct. 3. Upload your CSV file. 4. Click the **Start Sending** 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, add a note, or disable them. **Required & optional fields:** | Field Name | Required | Description | |------------|----------|-------------| | `code` | Yes | The unique gift card code you want to update. You must provide either the code or the internal card ID. | | `balance` | No | Set a new balance for the gift card. Use `+` or `-` prefix to increment or decrement balance (e.g. `+10` or `-10`). | | `expires_on` | No | Change the expiration date. Use `YYYY-MM-DD` format. | | `note` | No | Add or overwrite the internal note. | | `disabled` | No | Set to `TRUE` to disable the card. Please note that this action cannot be reverted. | | `recipient_email` | No | The email address of the person receiving the gift card. | | `customer_email` | No | The purchaser's email. If provided, a confirmation can be sent to them. | | `notify_customer` | No | Set `true` if you want to send notification to a customer. | | `notify_recipient` | No | Set `true` if you want to send notification to a recipient. | **How to update gift cards:** 1. Navigate to the **Update** tab. 2. Prepare a CSV file containing the `code` of each gift card you wish to modify, along with the fields you want to update. 3. Upload the file and click **Start Update**. --- ## 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. | | `code` | No | You can specify an existing code. If not set, the app will generate a gift code during the import. | | `customer_id` | No | Associate the card with an existing Shopify customer. (Please note: notification will be sent to a customer. Please use `recipient_email` if you would like just to assign a customer.) | | `expires_on` | No | The expiration date of the imported card. | | `recipient_email` | No | The email address of the person receiving the gift card. | | `customer_email` | No | The purchaser's email. If provided, a confirmation can be sent to them. | | `notify_customer` | No | Set `true` if you want to send notification to a customer. | | `notify_recipient` | No | Set `true` if you want to send notification to a recipient. | **How to import gift cards:** 1. Navigate to the **Import** tab. 2. Prepare your CSV file with the required `code` and `initial_value` columns. 3. Upload your file and click **Start Import**. --- ## Monitoring Your Bulk Jobs After starting a bulk action, you can monitor its progress on the **Results** tab. Your job will be processed in the background, so you can safely navigate away from the page. **Job statuses:** - **Processing** — The job is currently active. - **Completed** — The job finished successfully, and all rows in your file were processed. - **Completed with Errors** — The job finished, but one or more rows in your file failed. - **Failed** — The job could not be started or a fatal error occurred. To see more details, click on a job in the list. This will show you which specific rows failed and provide an error message so you can correct your file and re-upload if necessary. ## Common Errors & Troubleshooting - **Validation Error / Invalid Payload** — This usually means your CSV file is empty, not formatted correctly, or the header row is missing. Please use our provided template. - **"Missing required field" Error** — One or more rows in your file are missing a value in a required column (e.g., a missing `initial_value` when generating cards). Check the job results to see which rows were affected. - **"Rate Limit" Errors** — Our system automatically manages requests to Shopify to prevent errors. If you see a note about rate limiting, it simply means the job may take a little longer to complete as the system safely paces the requests. No action is needed from you. --- ## Reload Balance (Top-up) Source: https://docs.syncu.be/giftcard-hero/features/reload-balance/ # Reload Balance (Top-up) The Reload Balance page lets you find gift cards and manually adjust their balances. Go to **Reload Balance** in the left navigation. --- ## Finding a gift card The page shows a searchable, paginated list of gift cards. - **Search by code** — enter the last characters of the gift card code - **Search by email** — enter the customer's email address The list shows each card's code (partially masked), customer email, current balance, initial value, and status. Use the **Previous** / **Next** buttons to page through results. If the feature requires an additional Shopify permission scope, a warning banner appears with a **Give additional scope** button to grant access. --- ## Adjusting a balance Click the adjust button on a card in the list to change its balance. This is useful for: - **Store credit programs** — manually add credit as a goodwill gesture or compensation - **Loyalty rewards** — top up a card when a customer reaches a spending threshold - **Corrections** — fix a balance that was set incorrectly At POS, staff can also reload cards directly through the GiftCard Hero POS tile. See [[pos-integration|POS Integration]] for details. --- ## Configuration Click **Configuration** in the page header to open the reload settings. ### Reload limit A badge shows whether the **$10,000 reload limit** is **Enabled** or **Disabled**. - Click **Increase limit** to raise the maximum allowed top-up amount (requires the `write_draft_orders` Shopify scope) - Click **Decrease limit** to return to the standard $10,000 cap If the `write_draft_orders` scope is missing, a warning banner appears with a **Give additional scope** button. ### Email notification template Configure the email sent to the cardholder after a balance is reloaded. | Field | Notes | |-------|-------| | **Email subject** | Required. Subject line of the notification | | **Email body** | Required. Body text of the notification | **Available placeholders:** | Placeholder | Outputs | |-------------|---------| | `{first_name}` | Customer's first name | | `{last_name}` | Customer's last name | | `{email}` | Customer's email address | | `{initial_value}` | Original face value of the gift card | | `{balance}` | Balance before the reload | | `{new_balance}` | Balance after the reload | | `{last_characters}` | Last digits of the gift card code | | `{reload_amount}` | Amount added in this transaction | Both fields are required — if either is left empty, validation errors appear on save. --- ## Storefront reload --- ## Balance Check Widget Source: https://docs.syncu.be/giftcard-hero/features/balance-widget/ # Balance Check Widget The balance check widget lets customers enter their gift card code on your storefront and instantly see their remaining balance — without going to checkout. This reduces "how much is left on my card?" support requests and gives customers confidence before they shop. --- ## How it works 1. Customer visits your store's balance check page or an embedded widget 2. They enter their gift card code 3. The widget shows the current balance and expiry date (if one is set) --- ## Balance check page Every store gets a hosted balance check page at: ``` https://[your-store].myshopify.com/a/gifthero/balance ``` Share this link in your gift card emails, navigation menu, or anywhere customers might look for it. ### Embedding the widget on any page You can also embed the widget directly in your storefront by adding this HTML element where you want it to appear: ```html
``` GiftCard Hero's script injects the widget into this container automatically. --- ## Configuration To enable the widget and set its behavior, go to **Balance Widget** (or **Configuration**) in the left navigation. See [[configuration|Widget Configuration]] for the full settings reference, including: - Enabling / disabling the widget - Product recommendations after a balance check - Allowing customers to apply the card to their cart from the widget - Cart progress bar - Auto-open delay - Text and title customization --- ## Sharing the balance check link Good places to share the balance check URL: - The "Check Balance" button in the gift card delivery email - Your store navigation ("Gift Cards" or "Check Balance" menu item) - Order confirmation and shipping notification emails - Your customer account page --- ## Customer account balance view Customers logged in with a Shopify account can see all their gift cards — including balances — in the **My Gift Cards** section of their customer account portal. See [[customer-account|Customer Account Portal]] for details. --- ## Troubleshooting **Widget doesn't appear** - Confirm the widget is enabled in [[configuration|Widget Configuration]] - If using the embed method, check that `
` is present in the page source - Hard-refresh the page (Cmd/Ctrl + Shift + R) to bypass Shopify's theme cache - Check if theme extension is enabled for your theme **Balance looks stale after a recent redemption** - The widget caches balance lookups briefly. A customer who checks immediately after redeeming a card may briefly see the pre-redemption balance. This resolves itself within a minute. --- ## Balance Check Widget — Configuration Source: https://docs.syncu.be/giftcard-hero/features/configuration/ # Balance Check Widget — Configuration The Configuration page controls the balance check widget for your storefront. Go to **Balance Widget** in the left navigation. --- ## Enable / disable The status badge at the top shows whether the widget is **Enabled** or **Disabled**. Click the toggle button to switch. When the widget is disabled, the balance check page and the embed code are both inactive — no widget appears on your storefront. --- ## Balance check page GiftCard Hero provides a hosted balance check page accessible at: ``` https://[your-store].myshopify.com/a/gifthero/balance ``` Use the **Copy** button to copy the URL, or **Open page** to preview it in a new browser tab. ### Embedding the widget To embed the balance check widget anywhere in your storefront, add this HTML to the target page: ```html
``` GiftCard Hero's storefront script detects this element and injects the widget into it automatically. --- ## Widget behavior options These checkboxes control what happens after a customer enters their gift card code: | Option | Description | |--------|-------------| | **Offer products at a similar price to card balance** | After a balance check, show product recommendations priced near the card's remaining value | | **Show main toggle button bubble** | Display a floating action button on the page that customers can click to open the widget | | **Allow applying card balance to cart from widget** | Let customers apply their gift card to the cart directly from the widget, without going to checkout | | **Show cart / balance progress bar** | Display a progress bar showing how much of the card's balance covers the current cart total | | **Show cart / balance progress bar on cart change** | Update the progress bar automatically as cart contents change | | **Allow applying multiple gift cards** | Let customers apply more than one gift card at a time | > The progress bar options are only active when **Allow applying card balance to cart** is enabled. ### Auto-open on page load Enter the number of seconds after which the widget opens automatically (e.g., `5` = opens 5 seconds after page load). Set to `0` (or leave blank) to require the customer to open it manually by clicking the toggle button bubble. --- ## Widget text and design To customize the widget's heading and surrounding text, go to the **Look and Feel** sub-page (accessible from the Balance Widget section in the navigation). There you can set: - **Title** — the heading displayed above the widget - **Text before widget** — HTML content shown above the balance check input - **Text after widget** — HTML content shown below the input --- ## Email Templates Source: https://docs.syncu.be/giftcard-hero/features/email-templates/ # Email Templates The Email Template page controls the emails GiftCard Hero sends when a gift card is issued. Go to **Email Template** in the left navigation. --- ## Template sections The email template page has three main sections plus optional settings. ### Language Use the language dropdown to select which language you're configuring. When a gift card is sent, GiftCard Hero uses the language that matches the customer's locale. If no translation is configured for that locale, the default is shown. ### Email text for purchaser Enter the custom message shown in the email sent to the **buyer** (the person who purchased the gift card). This email is sent when a recipient has been specified on the gift card. Accepts plain text or HTML. ### Email text for recipient Enter the custom message shown in the email sent to the **recipient** (the person receiving the gift card). This is the main gift card delivery email. Accepts plain text or HTML. --- ## Additional settings These checkboxes control what appears in the generated email: | Option | Effect | |--------|--------| | **Show gift code directly in email** | Include the gift card code in the email body. By default, customers need to click "View gift card" to reveal the code. Enabling this shows the code inline. | | **Hide "View gift card" button** | Remove the button that links to the animated gift card page. Useful when you're showing the code directly and don't want the visual page. | | **Include greeting message, recipient name and from** | Add the sender's personal message, the recipient's name, and the sender's name to the email. | --- ## Generating and previewing Click **Generate email template** to render a preview of the email based on your current settings. The preview opens in a modal so you can review the final output before it goes to customers. Click **Cancel** to discard changes. --- ## Reminder email template The email sent for unused balance reminders has its own separate template. Access it from the [[reminders|Unused Balance Reminders]] page → **Change email template**. The reminder template has the same structure (language, purchaser text, recipient text, checkboxes) but controls the reminder-specific messaging. --- ## Troubleshooting **Variables showing as literal text (e.g., `{{recipient_name}}`)** Check spelling and case — variable names are case-sensitive. Ensure `{{` and `}}` are both present with no extra spaces inside. **Email going to spam** - Verify your Shopify email sending domain's SPF and DKIM records - Avoid spam trigger words in the subject - Test the email in multiple clients before sending to customers **Logo not displaying in some email clients** Some clients block external images by default. Use an image hosted on a reliable CDN — GiftCard Hero's template handles this automatically for images uploaded through the app. **Video greeting doesn't appear in the email** Video greetings cannot be embedded directly inside the email - email clients (Gmail, Outlook, Apple Mail, etc.) don't reliably support inline video playback, so any embedded video would show as a broken attachment for most recipients. Instead, the email should contain a button/link that opens the animated gift card page on your store - that's where the video plays alongside the personal message, image, and gift card code. If recipients aren't reaching the video at all, the most common cause is that the email template doesn't include a link to the gift card page. You have two options: - (Recommended) Add a "View gift card" button/link to the animated gift card page - this gives recipients the full unboxing experience. - Add a direct link to the uploaded video file in the email - opens the video in a new tab when clicked. Less rich but more direct. Reach out to support if you'd like help adding either to your template. If the link is already in the template and the video still isn't playing on the gift card page, share the order number or gift card link with support so we can investigate. **Custom HTML image renders broken or stretched in email** If you've added a custom `` tag in the template (or in Shopify's native gift card notification under **Notifications → New gift card**) and the image looks distorted or doesn't render in the recipient's inbox, try removing the `width` and `height` attributes from the tag. Many email clients ignore CSS sizing and rely on the inline attributes, but inconsistent values cause some clients to drop the image entirely. Letting the image render at its native size, or using only inline `style="max-width:..."`, is the most compatible approach. --- ## Email preview --- ## PDF Version of Gift Cards Source: https://docs.syncu.be/giftcard-hero/features/pdf-version/ # PDF Version of Gift Cards Gift Card Hero can generate a printable PDF version of any gift card. The PDF matches the **print version** of the gift card page — the same design your customer sees when they open their gift card link. ## Adding a PDF Download Link to the Email By default, the PDF link is not included in the email. To add it, edit your gift card notification template in Shopify: 1. Go to **Shopify Admin → Settings → Notifications → Customer notifications → Gift card created** 2. Click **Edit code** 3. Add the following link anywhere in the template body: ```html Download PDF ``` 4. Click **Save** The recipient will now see a **Download PDF** button in their gift card email. ## PDF Design The PDF is generated from the live gift card page and reflects the current design — including your custom CSS, branding, and card design. Any design changes made in the app are automatically reflected in new PDFs. ## Resending the Gift Card Email If a customer didn't receive their email or needs the PDF resent: 1. Open the gift card in **Shopify Admin → Products → Gift Cards** 2. Find the **Gift Card Hero** block in the page sidebar 3. Select the recipient type and click **Send** See [Using the Admin Block](admin-block) for details on adding the block if it's not visible. --- ## Unused Balance Reminders Source: https://docs.syncu.be/giftcard-hero/features/reminders/ # Unused Balance Reminders Reminders are automated emails sent to customers who have an unused gift card balance. Most unredeemed gift cards are simply forgotten — a timely reminder can recover that revenue and bring customers back. Go to **Reminders** in the left navigation. --- ## Enabling reminders The status badge at the top shows whether reminders are **Enabled** or **Disabled**. Click the toggle button to switch. When disabled, no reminder emails are sent and the **Send reminder** button is inactive. --- ## Configuration options ### Delay (days after purchase) Set how many days after a gift card is purchased before the first reminder is sent. For example, `30` means reminders go out 30 days after the card was issued if it hasn't been used. ### Marketing consent filter Check **Only email customers who accept marketing at checkout** to restrict reminders to customers who opted in to marketing emails. This is recommended for GDPR compliance and to avoid unsubscribe complaints. ### Send a second reminder Enable **Send a second reminder** to follow up with customers who still haven't used their balance. Set **Send second reminder after** to the number of days to wait (counted from the first reminder) before the follow-up is sent. --- ## Delivery method Choose how reminder emails reach your customers: - **App email (built-in)** — the default. GiftCard Hero renders the reminder template (below) and sends the email itself. - **Klaviyo** — instead of sending the email itself, GiftCard Hero sends a **Gift Card Reminder** event to your Klaviyo account, and a Flow you build in Klaviyo sends the email. The built-in template is **not** used in this mode. The **Klaviyo** option becomes selectable only after you connect Klaviyo in **Settings → Integrations**. See [Integrations](integrations.md) for setup and how to build the Flow. --- ## Send reminder for all gift cards Click **Send reminder** to immediately trigger a reminder for all currently eligible cards (cards that are active and have an unused balance). This button is only available when reminders are enabled. Use this for a one-time campaign — for example, when you first enable reminders and want to reach all existing cardholders right away. --- ## Reminder email template The reminder email has its own template, separate from the gift card delivery email. Click **Change email template** to go to the reminder template editor. In the template editor you can customize: - **Language** — select the language for the template - **Email text for purchaser** — the message sent when a purchaser has an unused card - **Email text for recipient** — the message sent when a recipient hasn't used their card - **Show gift code directly in email** — include the card code in the email body - **Hide "View gift card" button** — remove the link to the gift card page - **Include greeting message, recipient name and from** — add personalization fields to the email Click **Generate email template** to preview the rendered email. --- ## Why reminders matter Industry data shows that a significant percentage of gift cards are never fully redeemed. Each unredeemed card represents revenue your customer has already paid. Reminder emails convert dormant balances into actual purchases at very low cost. Even a single reminder campaign sent to all cardholders typically drives a measurable uplift in redemption rate and repeat purchase revenue. --- ## Compliance notes Reminder emails are considered **marketing emails** in most jurisdictions and must: - Include an unsubscribe option (GiftCard Hero includes this automatically) - Only be sent to customers who have consented to marketing (use the **Marketing consent filter** setting) - Comply with GDPR, CAN-SPAM, and similar regulations in your region Consult your legal counsel if you're unsure about consent requirements. --- ## Integrations Source: https://docs.syncu.be/giftcard-hero/features/integrations/ # Integrations GiftCard Hero can connect to external platforms to extend how gift card events are delivered. Go to **Settings → Integrations**. !!! note "Current scope" The Klaviyo integration currently works **only with [Unused Balance Reminders](reminders.md)**. Support for promotions, mass send, and loyalty is planned. --- ## Klaviyo Klaviyo is an **event-based** marketing platform. Instead of GiftCard Hero sending the reminder email, GiftCard Hero sends an **event** to your Klaviyo account, and a **Flow** that you build in Klaviyo sends the actual email. This lets you use your own branding, segmentation, and A/B testing. ### 1. Get a Private API Key In Klaviyo, go to **Settings → API keys → Private API Keys → Create Private API Key**. Give the key a name (for example, `GiftCard Hero`) and grant these scopes — or simply choose **Full Access**: - **Events: Write** — to send the reminder event - **Profiles: Write** — the event creates or updates the customer profile - **Accounts: Read** — used by the connection test Copy the key (it starts with `pk_`). Klaviyo shows it only once. ### 2. Connect in GiftCard Hero 1. Open **Settings → Integrations**. 2. Paste the key into **Private API key**. 3. Click **Test connection** — on success a banner shows your Klaviyo account name. 4. Check **Enable Klaviyo integration** and click **Save**. !!! note "Your key is stored securely" The API key is stored encrypted and is never shown again. You only need to re-enter it if you want to replace it. ### 3. Use Klaviyo for reminders In **Reminders**, set **Delivery method** to **Klaviyo**. From then on, eligible reminders send a **Gift Card Reminder** event to Klaviyo instead of an email from GiftCard Hero. ### 4. Build the Flow in Klaviyo Create a Flow triggered by the **Gift Card Reminder** metric. Each event includes these properties you can use in the email: | Property | Description | |---|---| | `gift_card_id` | Shopify gift card id | | `card_masked` | Masked code, e.g. `••••1234` | | `card_last4` | Last 4 characters of the gift card code | | `balance` | Remaining balance | | `amount_used` | Amount already spent | | `shop` | Store domain | | `reminder_id` | Internal id (used to prevent duplicate events) | The customer profile (email, first name, last name) is attached to the event automatically, so your Flow can match the customer and personalize the message. !!! warning "The built-in template is not used" When **Delivery method** is **Klaviyo**, the GiftCard Hero reminder template is not sent — the email content is fully controlled by your Klaviyo Flow. --- ## Notes ### Consent Reminders respect the **Marketing consent filter** in Reminder settings regardless of delivery method. Keep it enabled to comply with GDPR/CAN-SPAM and to avoid Klaviyo flagging your messages. ### Fallback If Klaviyo is selected but not usable — no key saved, the integration is disabled, or the saved key can't be used — GiftCard Hero falls back to sending the reminder through its built-in email, so customers still receive it. ### What is not sent The full, redeemable gift card code is **not** included in the event (Shopify does not expose it after the card is created). Use `card_masked` / `card_last4` for display, and link customers to your store or account page so they can view and use the card. --- ## Promotions Source: https://docs.syncu.be/giftcard-hero/features/promotions/ # Promotions Promotions let you automatically issue gift cards to customers when specific order conditions are met. Go to **Promotions** in the left navigation. This feature requires the `allowPromotions` flag on your plan. If Promotions doesn't appear in your navigation, contact support or upgrade your plan. --- ## Promotions list The promotions list shows all existing promotions in a table with these columns: - **Name** — the promotion's internal name (click to edit) - **Description** — a short description of what the promotion does - **Gift Card Value** — the value of the gift card issued when the promotion triggers Use the checkboxes to select multiple promotions for bulk deletion. Click **Delete promotions** in the action bar to remove the selected items. --- ## Creating a promotion Click **Add Promotion** to open the creation form. ### Promotion fields | Field | Description | |-------|-------------| | **Promotion Name** | Internal name for identifying this promotion (not shown to customers) | | **Description** | Optional description of the promotion's purpose | | **Gift Card Value** | The monetary value of the gift card that will be issued each time the promotion's conditions are met | ### Rules Use the rule builder to define when the promotion triggers. Rules are based on order-level conditions. Click **Add rule** to add a condition, and the trash icon to remove one. When all conditions in a rule are met for an order, GiftCard Hero automatically issues a gift card of the configured value to the customer. --- ## Editing a promotion Click the promotion's name in the list, or click **Edit** in the actions column, to open the edit form. The form is identical to the creation form. Changes take effect immediately for new orders — existing issued gift cards are not affected. --- ## Deleting promotions Select one or more promotions using the checkboxes and click **Delete promotions** in the bulk action bar. Deletion is permanent. --- ## How it works end-to-end 1. A customer places an order 2. GiftCard Hero evaluates the order against all active promotion rules 3. If an order matches a promotion's conditions, a gift card of the specified value is automatically created in Shopify 4. The gift card is sent to the customer via email The gift card is issued after the order is confirmed. The customer can use it on their next purchase. --- ## Payment Customization Source: https://docs.syncu.be/giftcard-hero/features/payments/ # Payment Customization The Payment Customization page lets you restrict which payment methods are available at checkout when a gift card is involved. Go to **Payments** in the left navigation. This feature uses Shopify's Payment Customization API. It requires the `write_payment_customizations` scope — if that scope is missing, a warning banner appears with an **Update permissions** button. ### Permissions If you see a yellow warning banner at the top of the page, the `write_payment_customizations` permission is not yet granted. Click the **Update permissions** button and complete the Shopify authorization flow to enable the feature. --- ## Gift Card Payment Rules Use the rule builder to define conditions under which gift card payment is blocked or restricted. This is useful when you want to prevent gift cards from being used in combination with certain products, customer segments, or order conditions. - Click **Add rule** to create a new condition - Each rule can be saved or deleted individually - Rules are evaluated at checkout in real time - Rules process top to bottom — place more specific rules higher in the list ### Examples - **Hide gift card payments for orders over $500:** Set condition to "Order Total > 500" - **Restrict gift card use from specific countries:** Set condition to "Customer Country = US" > A link to help documentation is available on this section for guidance on building complex rules. --- ## Restrict Payment Methods Use this section to hide specific payment methods at checkout when a customer is using a gift card. The section has two tabs: ### For eGift Cards Select the payment methods to hide when an eGift card is present in the order. A list of your store's available payment methods is shown with checkboxes. Tick a method to hide it when an eGift card is used. Common restrictions merchants set: - **Buy now / pay later** (Klarna, Afterpay) — prevents split-payment complexity - **Store credit / gift cards** — prevents payment loops - **Bank transfers** — avoids processing delays ### For Physical Gift Cards The same payment method list, but applied when a physical gift card is involved in the order. Click **Save** after making changes in either tab. --- ## Common use cases **Hide "Cash on Delivery" when a gift card is used** Some stores don't want cash-on-delivery orders paid partially with gift cards, because reconciling partial cash payments is complex. Restrict COD in the Physical Gift Cards tab. **Prevent gift card + store credit stacking** If you have a custom payment method for store credit, you can hide it when a gift card is already applied to prevent double-discounting. --- ## Notes - Shopify natively handles gift card validation at checkout — GiftCard Hero's payment customization controls which *other* payment methods are visible, not the gift card method itself. - Changes apply to all future checkouts immediately after saving. No theme changes are needed. --- ## POS Integration Source: https://docs.syncu.be/giftcard-hero/features/pos-integration/ # POS Integration GiftCard Hero adds a dedicated tile to Shopify POS that gives in-store staff gift card tools without leaving the POS screen. > **Not using Shopify POS?** If your store runs on a non-Shopify register — Square, Clover, Lightspeed, Zettle, and similar — see [Gift Cards on 3rd-Party POS (PWA)](third-party-pos.md) instead. --- ## What staff can do from POS - **Check a gift card balance** — enter or scan a code to see the current balance - **Reload a card** — add funds to an existing gift card - **Process a refund to a gift card** — apply a refund amount to a new or existing gift card - **View a customer's gift cards** — see all cards linked to a customer account - **Search by code or email** — look up cards by code characters or customer email --- ## Setup ### Step 1 — Enable the POS extension 1. In GiftCard Hero, go to **POS Tools** in the left navigation 2. Confirm the extension is active ### Step 2 — Add the tile to your POS layout 1. Open the Shopify POS app on your device 2. Go to **Settings → Apps** and confirm GiftCard Hero is listed and enabled 3. Add the GiftCard Hero tile to your POS home screen layout The tile appears on the POS home screen for all staff at that location. --- ## POS extension capabilities The GiftCard Hero POS extension installs multiple components into Shopify POS: ### Home tile A tile on the POS dashboard that opens the main GiftCard Hero interface. From here staff can check balances and reload cards. ### Check Balance Enter or scan a gift card code to see the current balance. The balance is displayed clearly with the currency format from your store settings. ### Reload Balance Add funds to a gift card at the register. Search for the card by code or customer email, then enter the amount to add. ### Order Refund When processing a return on an order, staff can access a refund action directly from the order details screen. This lets them issue the refund amount as a gift card instead of returning it to the original payment method. ### Customer Gift Cards When a customer is added to a POS transaction, staff can view all gift cards associated with that customer's account — including current balances — directly in the customer details block. --- ## Accepting a gift card as payment Gift card redemption at checkout is handled natively by Shopify POS — no GiftCard Hero action is needed. When a customer wants to pay with a gift card: 1. Add items to the cart as normal 2. Tap **Charge** 3. Select **Gift Card** as the payment method 4. Scan or type the code Shopify POS deducts from the balance automatically. --- ## Advanced POS tools Go to **POS Tools** in the GiftCard Hero admin (the **posTools** route, accessible from the main navigation) for legacy check-balance and change-balance tools. These are provided for compatibility with older POS setups. The current recommended approach is the Shopify POS UI Extension (the tile) described above. --- ## Troubleshooting ### The GiftCard Hero tile doesn't appear in POS 1. Confirm the POS extension is enabled in GiftCard Hero → POS 2. Update the Shopify POS app to the latest version 3. Go to POS **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: force-close and reopen the POS app ### "Failed to load" error in the POS tile 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 ### Balance check showing wrong amount The balance shown is fetched live from Shopify. If it looks stale, check the device's internet connection and try again. ### QR code in gift card email/balance page won't scan in POS Symptoms: - Every gift card email shows what looks like the same QR code - Scanning that QR in Shopify POS does nothing or returns "not found" - The QR added to Apple Wallet *does* scan correctly Cause: the gift card balance page (`/gift_cards/{id}/{token}`) is missing the dynamic `QrCode` Liquid object that's needed to render the per-card QR. When that object isn't exposed, GiftCard Hero falls back to a static placeholder image, so every email ends up with the same non-scannable code. Fix: contact GiftCard Hero support with the affected store domain - we'll patch the rendering on our side so the per-card QR is generated correctly. After the fix, both the email and the balance page will show the unique QR that scans into POS. --- ## Gift Cards on 3rd-Party POS (PWA) Source: https://docs.syncu.be/giftcard-hero/features/third-party-pos/ # Gift Cards on 3rd-Party POS (PWA) If your physical store runs on a register **other than Shopify POS**, that system has no way to read or update your Shopify gift cards. The **GiftCard Hero POS app** closes that gap. It's a small standalone web app your staff open on any phone or tablet to **check balances, redeem (spend), and activate Shopify gift cards** — right next to your third-party terminal. Everything the app does writes straight back to your Shopify gift card records in real time, so balances stay in sync with what customers see on their card, email, and account. --- ## When you need this - **You use Shopify POS** → you don't need this app. Use the native [POS Integration](pos-integration.md) tile instead, which handles gift card payment at checkout for you. - **Your in-store checkout runs on a non-Shopify register** → this app is your bridge. It works alongside popular POS systems such as: - **Square** - **Clover** - **Lightspeed Retail** (formerly Vend) - **Zettle by PayPal** - **SumUp** - **Toast** - **Loyverse** - **Epos Now** - **Erply** - …or any other register with no native Shopify gift card support. **How it fits into a sale:** ring up the order in your POS as usual, then use the GiftCard Hero POS app to redeem the customer's gift card. The app tells you how much the card covers and **how much is left to charge** on your POS — you take that remainder as a normal payment. --- ## What staff can do - **Check a balance** — type a code or scan the card's QR/barcode - **Redeem (spend)** an amount from a card — a custom amount, a quick preset, or by order subtotal - **Activate / issue** a gift card by loading a balance onto a code (e.g. a pre-printed physical card) - **Review activity** — a log of what was issued and redeemed - **Fast re-entry** with a personal 4-digit PIN --- ## The app in short - **Web address:** [https://gifthe.ro](https://gifthe.ro) - **Installs separately** as a PWA (Progressive Web App) on any device with a modern browser. Once installed it gets its own app icon and runs full-screen, just like a native app. - **Independent sign-in.** It is not the Shopify admin. Each staff member signs in with their own **username and password** — accounts you create in the GiftCard Hero admin (see below). --- ## Setup Setup has three parts: create staff accounts, install the app on the device, and have each person sign in and set a PIN. ### Step 1 — Create POS user accounts Staff can't sign in until you create accounts for them. 1. In GiftCard Hero, open **POS Tools** 2. Switch to the **3rd party POS** tab 3. Click **Add User** 4. Fill in the details: - **Username** — the unique login name (case-insensitive) - **Full Name** — the display name for the person - **Password** — minimum 6 characters (entered twice to confirm) 5. Click **Save** Create one account per staff member — activity in the app is recorded per user. The **POS Users** table lists everyone with access, their **status**, **roles**, whether they've **set a PIN** yet, and when the account was created. ### Step 2 — Install the app on the device On the phone or tablet you'll use at the register: 1. Open a web browser and go to **[https://gifthe.ro](https://gifthe.ro)** 2. Install it to the home screen: - **Chrome / Edge (Android or desktop):** tap the install icon in the address bar, or open the menu → **Install app** / **Add to Home screen** - **Safari (iPhone / iPad):** tap **Share** → **Add to Home Screen** - **Android (other browsers):** open the menu → **Add to Home screen** 3. Open the new app icon — it launches full-screen, like a native app > Installing is optional — you can also just use the site in a browser — but installing gives a cleaner, distraction-free, app-like experience for the register. ### Step 3 — First sign-in and PIN 1. Open the app and enter the **username** and **password** you created in Step 1 2. On first sign-in you'll be asked to set a **4-digit PIN** 3. Enter and confirm the PIN, then continue The PIN is for quick re-entry, so staff don't retype the full password every time the app is reopened. It's stored securely and never shown again. --- ## Reviewing activity from the admin Every issue and redeem action from every staff member is also visible from the GiftCard Hero admin — no need to check each person's phone. 1. In GiftCard Hero, open **POS Tools → 3rd party POS** 2. Scroll to **Activity Log**, below the POS Users table — it shows the 10 most recent actions across all staff for this store 3. Click **View full report** to open the full Activity Log page, where you can: - **Search** by username, action, or gift card - **Filter** by action type (Issue / Redeem) and by **date range** - Page through results with the built-in pagination - Click **Export CSV** to download the currently filtered results as a spreadsheet Each row shows the date/time, staff member, action, the affected gift card (linked to its record in Shopify admin when available, otherwise shown as **n/a**), a **Details** column with the amount/order name/note for that action, and whether it **succeeded or failed**. --- ## Daily use ### Redeem a gift card / check a balance 1. From the home screen, tap **Balance & Redeem** 2. Type the gift code, or tap **Scan** to read the card's QR/barcode with the camera 3. Pick the card from the results — you'll see the **masked code** and its **current balance** 4. Choose how much to redeem: - **Custom** — enter any amount - **Quick preset** — one tap for a common amount - **Order subtotal** — enter the full order total; the app shows how much the card covers and the **Remaining to charge** (the amount you still collect on your POS) 5. Optionally add an **order name** or an internal **note** 6. Tap **Redeem** — the balance is deducted from the Shopify gift card immediately If the amount you enter is more than what's on the card, the app redeems only up to the available balance and shows a warning. ### Activate / issue a gift card Use this to load a balance onto a card code — for example, to activate a pre-printed physical card at the counter. 1. From the home screen, tap **Issue Gift Card** 2. Type or scan the **gift code** 3. Enter the **amount** to load, plus an optional order name or internal note 4. Tap **Issue gift card** — the card is created in Shopify with that starting balance If a card with that code already exists, the app tells you instead of creating a duplicate. ### PIN lock and re-entry - When the app is reopened it locks and asks for the **PIN** — enter it to continue - **3 incorrect PINs** signs the user out; they sign back in with username and password - **Forgot the PIN?** Tap **Logout** on the lock screen, then sign in again with the username and password - To **change a PIN**, go to **Profile → Settings** (the current PIN is required) ### Activity log Open **Profile → Activity log** to see recent issue and redeem actions performed in the app, with amounts and timestamps. This view only shows the signed-in staff member's own actions — as the merchant, you can review activity across **all** staff from the admin (see [Reviewing activity from the admin](#reviewing-activity-from-the-admin) above). --- ## How this compares to Shopify POS | | Shopify POS | 3rd-party POS (this app) | |---|---|---| | Setup | [POS tile inside Shopify POS](pos-integration.md) | Separate PWA at gifthe.ro | | Sign-in | Your Shopify POS staff | Dedicated POS user accounts you create | | Take gift card as payment | Native — select **Gift Card** at checkout | Redeem in the app, charge the remainder on your POS | | Check balance / reload | Yes, from the tile | Yes, from the app | If you run **both** Shopify POS and another register in different locations, you can use both approaches side by side. --- ## Requirements & notes - **Internet connection required.** The app talks to Shopify in real time to read and update balances. - **Camera permission** is needed the first time you scan a code. If scanning isn't available, type the code instead. - **Redeeming debits the real gift card.** The balance change is the same one customers see on their card, gift card email, and customer account. --- ## Troubleshooting ### A staff member can't sign in - Double-check the username and password. Usernames are case-insensitive. - Confirm the account exists and is **Active** in **POS Tools → 3rd party POS**. - The message "Incorrect login or password" means the credentials don't match — re-create or re-share them if needed. ### The scanner won't open - Allow **camera permission** for the site in the browser's settings. - Some browsers only allow the camera over a secure (HTTPS) connection — gifthe.ro is served over HTTPS, so this is usually a permissions prompt that was dismissed. - As a fallback, type the gift code by hand. ### A cashier forgot their PIN Tap **Logout** on the lock screen and sign in again with the username and password. They can then set a new PIN in **Profile → Settings**. ### The balance looks wrong or out of date The balance is fetched live from Shopify. Search for the card again to refresh it, and check the device's internet connection. ### "Amount exceeds available balance" The card doesn't have enough balance for the amount entered. The app will redeem only up to the remaining balance — take the difference as a separate payment on your POS. --- ## Developer Tools Source: https://docs.syncu.be/giftcard-hero/features/developer-tools/ # Developer Tools The Developer Tools page provides API access, webhook configuration, headless mode, and advanced integration options. Go to **For Developers** in the left navigation. --- ## Storefront API The Storefront API lets your custom storefront code interact with GiftCard Hero's gift card data. - **Enable Storefront API** — toggle on to activate API access - **Disable gift card page animation** — removes the CSS animation on the gift card display page; useful for headless or custom template implementations Once enabled, your storefront can query gift card balance and status data via the Storefront API. > **Full API reference:** [Storefront API](../developer/storefront-api.md) --- ## REST API The REST API lets you integrate GiftCard Hero with external systems — CRMs, analytics dashboards, loyalty platforms, and more. ### Enabling Toggle **Enable REST API** to on. Then click **Send me access token** — GiftCard Hero sends the API access token to your store's admin email address. A **Postman collection** download link is available on the page for quick API exploration. ### Available endpoints | Method | Endpoint | Description | |--------|----------|-------------| | `POST` | `/api/external/gift-cards` | Create a gift card | | `POST` | `/api/external/gift-cards/{id}/disable` | Disable a gift card | | `GET` | `/api/external/gift-cards` | List gift cards (filterable by status) | | `GET` | `/api/external/gift-cards/{id}` | Get a single gift card | | `GET` | `/api/external/gift-cards/search?query=...` | Search gift cards by code or email | | `PUT` | `/api/external/gift-cards/{id}` | Update a gift card | | `PUT` | `/api/external/gift-cards/{id}/balance` | Update a gift card's balance | > **Full API reference:** [REST API Reference](../developer/rest-api.md) --- ## Webhooks GiftCard Hero can send HTTP POST requests to your server when specific gift card events occur. ### Setting up a webhook secret Click **Generate Secret** to create a signing secret. Use this secret on your server to verify that incoming webhook payloads are genuinely from GiftCard Hero — the signature is sent in the `X-GiftHero-Signature` header (HMAC-SHA256). Click **Regenerate Secret** to rotate the secret if it has been compromised. Update your server to use the new secret after regenerating. ### Webhook endpoints Configure your server URLs for these three webhook types: | Webhook | When it fires | |---------|--------------| | **Order with gift card** | An order containing a gift card product is created | | **Gift card payment** | A gift card code is applied as payment at checkout | | **Gift card balance change** | A gift card's balance is modified (top-up, redemption, or manual adjustment) | Enter your endpoint URL in each field and save. > **Full integration guide:** [Webhooks Integration Guide](../developer/webhooks.md) --- ## Custom Code Editor Add custom CSS and JavaScript to GiftCard Hero's storefront components without modifying your Shopify theme directly. Click **Open custom code editor** to open the editor. It has separate tabs for CSS and JavaScript. Use the custom code editor to adjust widget appearance, integrate analytics tracking, or connect third-party tools. --- ## Save Gift Card Data to Metafield When enabled, GiftCard Hero writes gift card data to a Shopify metafield on the customer record: - **Namespace:** `gift_hero` - **Key:** `cards_data` This makes gift card data accessible in Shopify email templates during gift card generation, as well as in Liquid templates and external integrations that can access Shopify customer metafields. **Disable gift card page animation for templates with suffix** — when using a custom template suffix on your gift card product page, this option removes the animation for that template specifically. --- ## Headless Mode Enable Headless Mode for custom or headless Shopify storefronts that don't use Shopify's standard theme system. Toggle **Enable Headless Mode** to on. A code snippet appears with placeholder values you replace with your store's specifics: | Placeholder | Replace with | |-------------|-------------| | `[MONEY_FORMAT]` | Your store's money format string | | `[PRODUCT_ID]` | Your gift card product's Shopify numeric ID | | `[MYSHOPIFY_DOMAIN]` | Your store's `.myshopify.com` domain | | `[ADD_TO_CART_CALLBACK]` | Your custom add-to-cart JavaScript function | | `[LOCALE]` | The active locale string (e.g., `en`, `fr`) | Copy the snippet and integrate it into your custom storefront codebase. > **Full setup guide:** [Headless Integration Guide](../developer/headless.md) --- ## Custom Fulfillment If you use a third-party fulfillment system, enable the custom fulfillment webhook to have GiftCard Hero send order data to your fulfillment endpoint whenever a gift card order is created. > **Warning:** Enabling custom fulfillment disables GiftCard Hero's automatic order fulfillment. Make sure your external system handles fulfillment before switching this on. The badge at the top of this section shows the current status (Enabled / Disabled). Click the toggle button to switch. --- ## Multi-Store (Store Networks) Source: https://docs.syncu.be/giftcard-hero/features/multistore/ # Multi-Store (Store Networks) The Multi-Store feature lets you link two or more Shopify stores so that gift cards issued on one store work across all connected stores. Go to **Multi-Store** in the left navigation. This is useful for: - Brands operating separate stores for different regions or markets - Franchises where each location has its own Shopify store - Wholesale and retail stores that share the same customer base --- ## Connecting a store To add a store to your network: 1. In the **Multi-Store** page, enter the `.myshopify.com` domain of the store you want to connect (e.g., `my-other-store.myshopify.com`) 2. Click **Add store** The other store must also have GiftCard Hero installed. Each store in the network needs its own GiftCard Hero subscription. A secondary store that has been connected will see a banner with information about the network connection. --- ## Viewing connected stores The **Stores in the network** section shows a table of all connected stores with their name and email. If no stores are connected yet, you'll see the message: *"Store isn't connected to any network."* --- ## How cross-store gift cards work Once stores are connected, a gift card issued on any store in the network can be redeemed on any other store in the network. The balance resolution happens transparently — from the customer's perspective, the card works the same everywhere. --- ## Considerations - **Separate subscriptions** — each store needs its own active GiftCard Hero subscription - **Currency** — if stores operate in different currencies, review your settings to ensure cross-store redemptions are handled correctly - **Analytics** — each store's dashboard shows its own data independently; there is no single unified cross-store dashboard --- ## Troubleshooting **"Store isn't connected to any network"** Verify that GiftCard Hero is installed on both stores and that the `.myshopify.com` domain was entered without typos. **Card not working in a secondary store** Confirm both stores appear as connected in the Multi-Store section of each store's GiftCard Hero admin. If one store has been uninstalled or the subscription lapsed, the network connection may have broken. See also: [[multi-location-retail|Multi-Location Retail]] for operational guidance on running a gift card program across multiple locations. --- ## Customer Account Portal Source: https://docs.syncu.be/giftcard-hero/features/customer-account/ # Customer Account Portal GiftCard Hero includes a Shopify Customer Account extension that adds a **My Gift Cards** page to your customers' account area. Customers can view all their gift cards and current balances without contacting support. --- ## What the extension does When a customer logs into their Shopify account and navigates to **My Gift Cards**, they see a list of gift cards associated with their account — including current balances. This reduces support requests about balance inquiries and gives customers a convenient self-service option. --- ## Installation ### Step 1: Access Theme Settings Go to **Shopify Admin → Online Store → Themes** → click **Customize** ### Step 2: Navigate to Customer Accounts Click on **Checkout and customer accounts** ### Step 3: Add the Extension Click the **Apps gear icon** → select **Gift Card Hero - "My Gift Cards"** → click **Accounts** ### Step 4: Enable and Save Press **Add to menu** → enter a preferred menu label → click **Save** --- ## How it works The extension is built as a Shopify Customer Account UI Extension targeting the customer account portal pages. It uses the Storefront API to fetch gift card data for the logged-in customer. Because it integrates with Shopify's Customer Account system: - Only gift cards linked to the customer's account are shown - The data is fetched securely — customers only see their own cards - It works with Shopify's new Customer Account experience --- ## Card association For a gift card to appear in a customer's account, the card must be associated with their customer record. This typically happens when: - The customer purchases a gift card while logged in - A gift card is issued directly to a customer's email from the GiftCard Hero admin - The customer redeems a gift card at checkout while logged in If a customer has a card that isn't showing in their account, they can use the [[balance-widget|Balance Check Widget]] to look up the balance by entering the code directly. --- ## Availability This feature requires that your store uses **Shopify's Customer Account** system (the newer customer account experience, not the classic account pages). The extension is installed automatically when GiftCard Hero is installed — no additional configuration is needed in most cases. --- ## Testing To verify the extension is working: 1. Create a test Shopify customer account 2. Issue a gift card to that customer's email via GiftCard Hero (**Issue e-Gift card**) 3. Log in as that customer and navigate to the customer account 4. Look for the **My Gift Cards** section 5. Confirm the card and its balance appear correctly --- ## Gift Card Hero REST API Source: https://docs.syncu.be/giftcard-hero/developer/rest-api/ # Gift Card Hero REST API The REST API lets you manage gift cards programmatically from external systems — CRMs, analytics dashboards, loyalty platforms, fulfillment services, and more. --- ## Base URL All API requests use the following base URL: ``` https://gifthero.syncu.be/api/external ``` --- ## Authentication Every request must include a Bearer token in the `Authorization` header: ``` Authorization: Bearer YOUR_API_TOKEN ``` To obtain your API token, go to **For Developers** in the left navigation and enable the REST API. Click **Send me access token** — the token is sent to your store's admin email address. --- ## Endpoints ### List gift cards ``` GET /gift-cards ``` **Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `status` | string | Filter by gift card status | | `limit` | integer | Maximum number of results (max 250) | | `since_id` | string | Return results after this gift card ID | | `fields` | string | Comma-separated list of fields to include | --- ### List gift cards with transactions ``` GET /gift-cards/transactions ``` Returns gift cards with their full transaction history. Supports cursor-based pagination. **Pagination:** | Parameter | Type | Description | |-----------|------|-------------| | `limit` | integer | Results per page (default 50) | | `page_info` | string | Cursor for the next page of results | **Filters:** | Filter | Type | Description | |--------|------|-------------| | `query` | string | Search query | | `balance_status` | string | One of: `full`, `partial`, `empty`, `full_or_partial` | | `created_at` | string | Filter by creation date | | `expires_on` | string | Filter by expiration date | | `source` | string | One of: `manual`, `purchased`, `api_client` | | `status` | string | One of: `disabled`, `enabled`, `expired`, `expiring` | | `initial_value` | string | Filter by initial value | All filters use AND logic when combined. --- ### Get a single gift card ``` GET /gift-cards/{gift_card_id} ``` Returns the full details of a single gift card by its ID. --- ### Create a gift card ``` POST /gift-cards ``` **Request body:** ```json { "note": "Loyalty reward", "initial_value": "50.00", "code": "ABCD-EFGH-IJKL-MNOP", "template_suffix": "custom" } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `note` | string | No | Internal note for the gift card | | `initial_value` | string | Yes | Starting balance | | `code` | string | No | Custom gift card code (must be unique; auto-generated if omitted) | | `template_suffix` | string | No | Shopify template suffix | > **Important:** Gift card codes cannot be retrieved after creation. Only the last 4 characters are returned in subsequent API responses. Store the full code at creation time if you need it. --- ### Update gift card balance ``` PUT /gift-cards/{gift_card_id}/balance ``` **Request body:** ```json { "balance": "100.00" } ``` Sets the gift card's balance to the specified value. --- ### Update a gift card ``` PUT /gift-cards/{gift_card_id} ``` Only the following fields can be updated: | Field | Type | Description | |-------|------|-------------| | `expires_on` | string | Expiration date | | `note` | string | Internal note | | `template_suffix` | string | Shopify template suffix | --- ### Disable a gift card ``` POST /gift-cards/{gift_card_id}/disable ``` Permanently disables the gift card. This action cannot be undone. --- ### Search gift cards ``` GET /gift-cards/search ``` **Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `order` | string | Sort order | | `query` | string | Search query | | `limit` | integer | Maximum number of results | | `fields` | string | Comma-separated list of fields to include | **Indexed fields** (available for search queries): `created_at`, `updated_at`, `disabled_at`, `balance`, `initial_value`, `amount_spent`, `last_characters` --- ### Assign gift card codes to an order ``` POST /gift-cards/assign-to-order ``` Assigns gift card codes to a Shopify order. Supports both single and multiple code assignment. **Single code:** ```json { "orderId": "1234567890", "giftCode": "ABCD-EFGH-IJKL-MNOP" } ``` **Multiple codes:** ```json { "orderId": "1234567890", "giftCodes": [ { "lineItemId": "111", "code": "ABCD-EFGH-IJKL-MNOP" }, { "lineItemId": "222", "code": "QRST-UVWX-YZ12-3456" } ] } ``` **Response:** ```json { "scheduled": true } ``` --- ## Pagination The transactions endpoint uses cursor-based pagination. The response includes a `Link` header with the cursor for the next page: ``` Link: ; rel="next" ``` Parse the `page_info` value from the `Link` header and pass it as a query parameter in your next request. --- ## Important notes - **Code uniqueness** — when creating gift cards with custom codes, each code must be unique. The API returns an error if a duplicate code is submitted. - **Code visibility** — gift card codes cannot be retrieved after creation. Only the last 4 characters (`last_characters`) are returned in API responses. - **Rate limits** — respect standard rate limits. If you receive a `429` response, back off and retry. --- ## Postman collection Download the Postman collection for quick API exploration: [Download Postman Collection](https://gifthero.syncu.be/downloads/gifthero.postman_collection.json.zip) --- ## Webhooks Integration Guide Source: https://docs.syncu.be/giftcard-hero/developer/webhooks/ # Webhooks Integration Guide Gift Card Hero sends HTTP POST requests to your server when specific gift card events occur. Use webhooks to keep external systems in sync with gift card activity in real time. --- ## Setup 1. Go to **For Developers** in the left navigation 2. Enable the REST API if not already enabled 3. Click **Generate Secret** to create a webhook signing secret > **Important:** The webhook secret is shown only once. Copy and store it securely. If you lose it, click **Regenerate Secret** to create a new one (and update your server accordingly). 4. Enter your endpoint URLs for each webhook type you want to receive --- ## Event types Gift Card Hero supports three webhook event types: | Event | Topic header value | When it fires | |-------|--------------------|---------------| | **Gift card order** | `gift_card_order` | An order containing a gift card product is created | | **Gift card payment** | `gift_card_payment` | A gift card code is applied as payment at checkout | | **Gift card balance change** | `gift_card_balance` | A gift card's balance is modified (top-up, redemption, or manual adjustment) | --- ## Delivery - **Method:** POST - **Timeout:** 6 seconds - **Retries:** Up to 5 retries with exponential backoff (starting at approximately 30 seconds) If your endpoint does not return a `2xx` response within 6 seconds, the delivery is considered failed and will be retried. --- ## Headers Every webhook request includes the following headers: | Header | Value | |--------|-------| | `Content-Type` | `application/json` | | `User-Agent` | `GiftHero-Webhooks/1.0` | | `X-GiftHero-Topic` | The event type (e.g., `gift_card_order`) | | `X-GiftHero-Signature` | HMAC-SHA256 signature for verification | --- ## Signature verification The `X-GiftHero-Signature` header contains an HMAC-SHA256 signature, hex-encoded and prefixed with `sha256=`. > **Important:** The signature is computed over a JSON object containing only `{ type, timestamp }` from the payload body — NOT the entire request body. ### Verification steps 1. Parse the request body and extract the `type` and `timestamp` fields 2. Construct the signing payload: `JSON.stringify({ type, timestamp })` 3. Compute the HMAC-SHA256 using your webhook secret as the key 4. Hex-encode the result and prefix with `sha256=` 5. Use a constant-time comparison to compare with the `X-GiftHero-Signature` header ### Example (Node.js) ```javascript const crypto = require('crypto'); function verifyWebhook(body, signature, secret) { const signingPayload = JSON.stringify({ type: body.type, timestamp: body.timestamp }); const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(signingPayload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); } ``` --- ## Payload schemas ### Gift card order (`gift_card_order`) Sent when an order containing a gift card product is created. ```json { "type": "gift_card_order", "timestamp": "2026-03-15T10:30:00.000Z", "order": { "id": "5551234567890", "name": "#1042", "email": "buyer@example.com", "createdAt": "2026-03-15T10:30:00.000Z", "lineItems": [ { "id": "11198765432100", "title": "Gift Card", "quantity": 1, "price": "50.00" } ] }, "giftCards": [ { "id": "987654321", "code": "****-****-****-AB12", "sku": "GC-50", "lineItemId": "11198765432100", "balance": "50.00", "currency": "USD", "lastCharacters": "AB12", "initialValue": "50.00", "customer": { "email": "buyer@example.com" }, "recipient": { "email": "friend@example.com" } } ] } ``` --- ### Gift card payment (`gift_card_payment`) Sent when a gift card code is applied as payment at checkout. ```json { "type": "gift_card_payment", "timestamp": "2026-03-16T14:22:00.000Z", "order": { "id": "5551234567891", "name": "#1043", "email": "shopper@example.com", "createdAt": "2026-03-16T14:22:00.000Z", "lineItems": [ { "id": "11198765432200", "title": "Running Shoes", "quantity": 1, "price": "89.99" } ] }, "giftCards": [ { "id": "987654321", "code": "****-****-****-AB12", "sku": "GC-50", "lineItemId": null, "balance": "0.00", "currency": "USD", "lastCharacters": "AB12", "initialValue": "50.00", "customer": { "email": "shopper@example.com" }, "recipient": null } ], "transaction": { "id": "txn_abc123", "amount": "50.00", "currency": "USD", "type": "debit", "createdAt": "2026-03-16T14:22:00.000Z" } } ``` --- ### Gift card balance change (`gift_card_balance`) Sent when a gift card's balance is modified through any means (top-up, redemption, or manual adjustment). ```json { "type": "gift_card_balance", "timestamp": "2026-03-17T09:15:00.000Z", "giftCard": { "id": "987654321", "code": "****-****-****-AB12", "balance": "75.00", "currency": "USD", "lastCharacters": "AB12", "previousBalance": "50.00" }, "change": { "amount": "25.00", "type": "credit", "reason": "manual_adjustment", "createdAt": "2026-03-17T09:15:00.000Z" }, "order": null } ``` The `order` field is included when the balance change is associated with an order (e.g., a checkout redemption) and is `null` for manual adjustments. --- ## Best practices - **Return 2xx quickly** — acknowledge the webhook immediately and process the payload asynchronously. Responses taking longer than 6 seconds are treated as failures. - **Handle duplicates** — the same event may be delivered more than once due to retries. Use the `timestamp` and event data to deduplicate. - **Verify HMAC signatures** — always verify the `X-GiftHero-Signature` header before processing any webhook payload. Reject requests with invalid signatures. - **Use idempotency keys** — design your webhook handler to be idempotent so that processing the same event twice produces the same result. - **Monitor failures** — if your endpoint is consistently failing, Gift Card Hero stops retrying after 5 attempts. Check your server logs and endpoint health regularly. --- ## Storefront API Source: https://docs.syncu.be/giftcard-hero/developer/storefront-api/ # Storefront API The Storefront API provides a JavaScript interface (`window.GiftHeroAPI`) for building custom gift card selection and purchase flows on your storefront. --- ## Initialization GiftCard Hero dispatches a custom event when the API is ready. Listen for the `gift.hero:initialized` event before calling any methods: ```javascript document.addEventListener('gift.hero:initialized', function () { const api = window.GiftHeroAPI; // API is ready to use }); ``` > **Note:** The `gift.hero:initialized` event fires after the GiftCard Hero storefront script has loaded and initialized. If the script has not been included on the page, the event will not fire. --- ## Methods ### addToCart(quantity?) Adds the configured gift card to the cart. ```javascript const result = await window.GiftHeroAPI.addToCart(1); // result: { status: 'success', data: { ... } } ``` **Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `quantity` | number | 1 | Number of gift cards to add | **Returns:** A promise that resolves with `{ status, data }`. --- ### generatePreview() Opens a preview modal showing how the gift card will look to the recipient. ```javascript window.GiftHeroAPI.generatePreview(); ``` --- ### getImages() Returns an array of available gift card images. ```javascript const images = window.GiftHeroAPI.getImages(); // [{ id: '...', src: 'https://...', alt: '...' }, ...] ``` --- ### getOptions() Returns the product options including available denominations. ```javascript const options = window.GiftHeroAPI.getOptions(); ``` --- ### getTranslations() Returns the current interface translations. ```javascript const translations = window.GiftHeroAPI.getTranslations(); ``` --- ### getVariants() Returns the product variants array. ```javascript const variants = window.GiftHeroAPI.getVariants(); ``` --- ### setCardData(cardData) Sets all gift card data at once. Use this instead of calling individual setters when you have all the data available. ```javascript window.GiftHeroAPI.setCardData({ variantId: '12345678', image: 'https://cdn.shopify.com/...', message: 'Happy Birthday!', from: 'Alice', deliveryDate: '2026-12-25', email: 'recipient@example.com', phone: '+1234567890' }); ``` **Fields:** | Field | Type | Description | |-------|------|-------------| | `variantId` | string | The selected variant ID | | `image` | string | URL of the selected card image | | `message` | string | Gift card message | | `from` | string | Sender's name | | `deliveryDate` | string | Scheduled delivery date (ISO format) | | `email` | string | Recipient's email address | | `phone` | string | Recipient's phone number | --- ### Individual setters | Method | Parameter | Description | |--------|-----------|-------------| | `setDeliveryDate(date)` | string | Set scheduled delivery date | | `setEmail(email)` | string | Set recipient email | | `setFrom(name)` | string | Set sender name | | `setImage(image)` | string | Set selected card image URL | | `setMessage(message)` | string | Set gift card message | | `setVariant(variantId)` | string | Set selected variant | --- ### validate() Validates the current gift card data. Returns validation errors if any required fields are missing. ```javascript const errors = window.GiftHeroAPI.validate(); ``` **Validation rules:** When an email or delivery date has been set, the following fields become mandatory: - `message` - `from` (sender name) - `deliveryDate` - `email` If these fields are not set when required, `validate()` returns the corresponding errors. --- ## React integration example A complete React integration example is available on JSFiddle. It demonstrates how to initialize the API, build a custom gift card selection UI, and handle the add-to-cart flow: [View React Example on JSFiddle](https://jsfiddle.net/syncubecommerce/k486aLyq/59/) --- ## Headless Integration Source: https://docs.syncu.be/giftcard-hero/developer/headless/ # Headless Integration Gift Card Hero supports headless Shopify storefronts that do not use Shopify's standard theme system. Enable headless mode to get an integration code snippet you embed in your custom storefront. --- ## Step 1: Enable headless mode Go to **For Developers** in the left navigation and toggle **Enable Headless Mode** to on. --- ## Step 2: Copy the integration code Once headless mode is enabled, a code snippet appears on the page. Copy this snippet — it contains the JavaScript and configuration needed to load Gift Card Hero on your storefront. --- ## Step 3: Replace placeholders The code snippet contains placeholder values that you must replace with your store's specific information: | Placeholder | Replace with | Example | |-------------|-------------|---------| | `[MONEY_FORMAT]` | Your store's money format string | `${{amount}}` | | `[PRODUCT_ID]` | Your gift card product's Shopify numeric ID | `7654321098765` | | `[MYSHOPIFY_DOMAIN]` | Your store's `.myshopify.com` address | `my-store.myshopify.com` | | `[ADD_TO_CART_CALLBACK]` | A JavaScript function that handles adding items to the cart | `addItemToCart` | | `[LOCALE]` | The active store locale | `en` | ### Money format The money format string determines how prices are displayed. You can find your store's money format in Shopify Admin under **Settings > General > Store currency**. Common formats: - `${{amount}}` — US dollars - `{{amount}} EUR` — Euros - `${{amount}} CAD` — Canadian dollars ### Product ID To find your gift card product's Shopify ID: 1. Open **Shopify Admin** 2. Go to **Products** 3. Click on your gift card product 4. Look at the URL in your browser's address bar — the numeric ID is at the end For example, if the URL is `https://admin.shopify.com/store/my-store/products/7654321098765`, the product ID is `7654321098765`. ### Add to cart callback The `[ADD_TO_CART_CALLBACK]` placeholder should be replaced with a JavaScript function name that your storefront uses to add items to the cart. This function receives the gift card variant and custom data from Gift Card Hero. ### Locale The `[LOCALE]` placeholder sets the language for the Gift Card Hero interface. Use a standard locale code such as `en`, `fr`, `de`, `es`, or `ja`. Defaults to `en` if omitted. --- ## After integration Once the snippet is embedded and placeholders are replaced, Gift Card Hero renders its gift card selection interface on your storefront. You can further customize the experience using the [Storefront API](storefront-api.md) for programmatic control over the gift card builder. --- ## Corporate Gifting Source: https://docs.syncu.be/giftcard-hero/use-cases/corporate-gifting/ # Corporate Gifting Corporate gifting programs are one of the highest-value use cases for eGift cards. Companies buy gift cards in bulk to reward employees, thank customers, or run incentive programs. GiftCard Hero makes it possible to handle these orders efficiently and professionally. ## How it typically works 1. A company contacts you wanting to purchase, say, 200 × $50 gift cards for their employees 2. You generate 200 cards and send each one to the employee's email address with a personalized message 3. The company receives a CSV confirmation with all codes for their records 4. Employees redeem their cards on your storefront ## Setting up for corporate orders ### Create a corporate gift card type Create a dedicated gift card type for corporate orders: 1. Go to **eGift Cards → Create gift card type** 2. Name it something internal like "Corporate — $50" (or make it flexible) 3. Design: use a clean, professional design (not the holiday-themed one) 4. Disable "show on storefront" — corporate cards are issued manually or via bulk, not purchased directly ### Prepare a recipient CSV template Give your corporate customer a CSV template to fill in: ``` email,first_name,last_name,message john@company.com,John,Doe,Thank you for your hard work this year! jane@company.com,Jane,Smith,Congratulations on your anniversary! ``` You receive this file, review it, then run the bulk send job. ## Running the bulk send 1. Go to **Bulk → Send** 2. Upload the filled-in CSV from the customer 3. Set the amount (e.g., $50 per card) 4. Set the sender name (e.g., the company name: "Acme Corp") 5. Set the gift card type to your corporate type 6. Click **Start Job** Each recipient gets a personalized email with their card code and the custom message. The company gets a results CSV when the job completes. ## Handling payment Corporate gift card orders are usually paid by invoice or purchase order. Your standard order flow handles this — create a Shopify draft order for the corporate customer for the total amount (200 × $50 = $10,000), mark it as paid when you receive payment, then run the bulk send. ## Providing reporting to corporate customers Many corporate customers want a report showing: - Which employees have redeemed their cards - Remaining balances - Total redemption value You can download the transaction history from **Dashboard → Full Report**, filter by date range and gift card type, and send the CSV to the customer. Note: individual redemption data may be sensitive — discuss with the customer what level of reporting they need. ## Automating repeat orders If a company places orders regularly (e.g., monthly employee rewards), you can streamline the process: 1. Keep their CSV template on file 2. They email you an updated list each month 3. You run the bulk send immediately For very high-volume programs, consider the API integration (see [[developer-tools|Developer Tools]]) to let the company trigger bulk sends themselves. ## Pricing for volume Consider offering volume pricing for large corporate orders — a discount on the card amount for orders above a threshold. Promotions aren't designed for this (they're customer-facing), so handle volume discounts at the invoice level. --- ## Holiday Gift Card Campaigns Source: https://docs.syncu.be/giftcard-hero/use-cases/holiday-campaigns/ # Holiday Gift Card Campaigns Gift cards are among the most purchased gifts during holidays. A well-timed campaign with seasonal designs and a bonus offer can significantly boost both gift card sales and overall store revenue during peak periods. ## Campaign planning Start 4–6 weeks before the holiday to give time for design, setup, and promotion. ### Key dates to plan around | Holiday | Campaign start | Key selling window | |---------|---------------|-------------------| | Christmas / Hanukkah | Early November | Nov 15 – Dec 24 | | Valentine's Day | Late January | Feb 1 – 14 | | Mother's Day | 3 weeks before | 2 weeks before | | Black Friday | Early November | BFCM weekend | | Father's Day | 3 weeks before | 2 weeks before | ## Step 1 — Create seasonal designs Create 2–3 themed gift card designs for the holiday: 1. Go to **eGift Cards → Design & Translations** 2. Upload your seasonal images (1200 × 750px) 3. Name them clearly: "Christmas 2026 — Classic Red", "Christmas 2026 — Winter Blue" For design inspiration, keep it simple: a seasonal color palette, your logo, and a clean holiday motif works better than a busy illustration. ## Step 2 — Create a themed gift card type Create a gift card type specifically for the campaign: 1. **Name:** "Holiday Gift Card 2026" (shown on storefront) 2. **Designs:** assign your seasonal designs and allow the buyer to pick 3. **Denominations:** offer a range including a mid-to-high anchor (e.g., $25, $50, $100, $200) — higher denominations sell well as gifts 4. **Delivery delay:** let buyers schedule delivery for Christmas morning ## Step 3 — Set up a promotion (optional but recommended) A "Buy $100, get $20 free" promotion drives urgency and increases average gift card order value. 1. Go to **Promotions → Add Promotion** 2. Type: Bonus on purchase 3. Trigger: minimum purchase $100 4. Reward: $20 bonus card to the buyer 5. Start date: your campaign start 6. End date: December 24 (or the day before the holiday) The bonus card goes to the buyer — rewarding them for gifting. ## Step 4 — Customize the seasonal email Update your gift card email template with holiday styling: 1. Go to **Email Template** 2. Adjust the header image to a seasonal one 3. Update the color scheme (deep red and gold for Christmas, pink for Valentine's, etc.) 4. Add a seasonal greeting in the email copy Don't forget to save a copy of your original template before editing — you'll want to revert after the season. ## Step 5 — Promote the campaign GiftCard Hero doesn't manage your marketing — that's your job. Common channels: - **Email campaign** — segment customers who've purchased in the last 12 months - **Homepage banner** — announce the seasonal design and bonus offer - **Social media** — "The perfect last-minute gift" messaging works well for gift cards - **Paid ads** — gift cards respond well to "last-minute gifting" targeting A key message that converts: "Guaranteed delivery — no shipping required." Digital gift cards solve the last-minute gifting problem better than physical products. ## Step 6 — Post-campaign cleanup After the holiday: 1. Set the seasonal gift card type to **inactive** (don't delete — you'll reuse next year) 2. Set the promotion to **inactive** 3. Restore your original email template You'll re-enable everything next year with minor updates. ## Measuring campaign success After the holiday, review in **Dashboard**: - Gift card sales during the campaign period vs. the same period last year - Redemption rate (did people actually use their holiday cards?) - Sales lift from card redemptions in January–March (holiday gift cards are typically used after the holiday) - Promotion ROI: bonus cards given out vs. incremental sales generated --- ## Selling Discounted Gift Cards Source: https://docs.syncu.be/giftcard-hero/use-cases/discounted-gift-cards/ # Selling Discounted Gift Cards Create appealing discounted gift cards by combining Shopify's automatic discount feature with specialized pricing. ## Part 1: Creating Automatic Discounts 1. Go to **Shopify Admin → Discounts → Create discount → Automatic discount** 2. Select **Amount off products** 3. Set the discount value (e.g., $25 off) 4. Under **Applies to**, select **Specific products** and choose your gift card products 5. Set optional conditions: minimum purchase, customer eligibility, usage limits, active dates 6. Save and ensure status shows **Active** ## Part 2: Configure Compare At Prices Gift Card Hero uses an inverted pricing structure for discounted cards: - **Price field** = full face value of the gift card - **Compare At Price** = discounted price customers actually pay > **Important:** This is inverted from typical Shopify products where compare-at price is usually higher. ### Configure each variant: 1. Go to **Products** → find your gift card → **Variants** 2. Set **Price** = full face value (e.g., $100.00) 3. Set **Compare at price** = discounted price (e.g., $75.00) ### Example pricing | Gift Card Value | Price Field | Compare At Price | Customer Pays | Savings | |---|---|---|---|---| | $25 | $25.00 | $20.00 | $20.00 | $5.00 | | $50 | $50.00 | $40.00 | $40.00 | $10.00 | | $100 | $100.00 | $75.00 | $75.00 | $25.00 | ## Part 3: Verify Your Setup Check on your storefront: - Sale badge appears on discounted variants - Crossed-out original price displays correctly - Actual purchase price matches compare-at price ## Troubleshooting - **Sale badge not appearing:** Check that compare-at price is set and less than regular price - **Wrong price displayed:** Verify price inversion (face value in price, discount in compare-at) - **Discount not applying at checkout:** Check discount active dates, usage limits, customer eligibility ## Best Practices - Use consistent discount percentages across denominations - Set active dates for seasonal promotions - Always test with a small purchase before launching --- ## Loyalty Rewards with Gift Cards Source: https://docs.syncu.be/giftcard-hero/use-cases/loyalty-rewards/ # Loyalty Rewards with Gift Cards Gift cards make an excellent loyalty reward mechanism. Unlike points systems that customers often forget or find confusing, a gift card is tangible — the customer knows exactly what they have and how much it's worth. ## Two approaches to gift card loyalty ### Approach A — Milestone rewards (most common) When a customer reaches a spending milestone, they automatically receive a gift card. Example: "Spend $500, get a $25 gift card." This requires some automation — either via a third-party loyalty app that integrates with GiftCard Hero, or a manual process. ### Approach B — Reloadable store credit card Issue every customer a $0 gift card when they create an account. Manually top it up with rewards credit as they earn it. This is simpler to set up but requires manual work to credit accounts. ## Setting up milestone rewards ### Option 1 — Manual (small stores) 1. At the end of each month, run a Shopify export of customers who hit the spending threshold 2. Prepare a CSV with their emails and reward amounts 3. Run a [[bulk-operations|Bulk Send]] job to issue the reward cards This works well for stores with a few hundred active customers per month. ### Option 2 — Via a loyalty app Many loyalty platforms (Smile.io, LoyaltyLion, Yotpo Loyalty) can trigger gift card issuance via the GiftCard Hero API when a customer earns a reward. 1. In the loyalty app, set up a reward action "Issue gift card worth $X" 2. Connect to GiftCard Hero using the API key from [[developer-tools|Developer Tools → API access]] 3. When a customer earns the reward, the loyalty app calls the GiftCard Hero API to issue the card automatically 4. The customer receives the gift card email immediately ### Option 3 — Webhook automation (advanced) Use GiftCard Hero webhooks + a tool like Zapier or a custom webhook handler: 1. Receive Shopify order webhooks 2. Check if the order pushes the customer over a threshold 3. If yes, call GiftCard Hero's API to issue a reward card This approach gives the most control and works without a third-party loyalty app. ## Reloadable store credit card setup 1. Create a gift card type called "Store Credit" (inactive on storefront — not for sale) 2. When a customer signs up or makes their first purchase, issue them a $0 card from this type 3. As they earn rewards, use **Reload Balance** to add credit to their card 4. The customer can check their balance at any time via the [[balance-widget|Balance Check Widget]] or their [[customer-account|Customer Account Portal]] ## Communicating the program to customers Gift card loyalty works best when customers know about it. Ideas: - Add a "How to earn rewards" section to your loyalty/FAQ page - Include a mention in your post-purchase email ("Earn a $25 reward card when you reach $500") - Send a notification when a customer is close to a milestone ("You're $47 away from your next reward!") ## Making loyalty cards feel special Differentiate loyalty reward cards from regular gift cards: - Use a distinct design (e.g., a "VIP" or "Member Rewards" branded card) - Write a personal message in the email: "Thank you for being one of our best customers" - Consider a slightly higher reward than competitors — loyalty is a retention investment ## Measuring effectiveness Track in **Dashboard**: - Redemption rate of loyalty cards (should be higher than standard gift cards — these customers are engaged) - Sales lift from loyalty card redemptions - Repeat purchase rate of customers who have received a loyalty reward Compare the cost of the rewards (face value of cards issued) against the lifetime value increase of rewarded customers. --- ## Multi-Location Retail Source: https://docs.syncu.be/giftcard-hero/use-cases/multi-location-retail/ # Multi-Location Retail This guide covers gift card operations for retailers with multiple physical locations, whether they use a single Shopify store with multiple locations or separate Shopify stores per location. ## Scenario A — One Shopify store, multiple locations This is the simpler setup. You have one Shopify store, and your POS devices at different locations all connect to it. ### How gift cards work - Cards issued at any location are valid everywhere (they're all on the same Shopify store) - Balances are shared and updated in real time across all locations - The [[dashboard|Dashboard]] shows total activity, filterable by location ### POS setup per location 1. Install the GiftCard Hero POS extension on your main Shopify store (one-time) 2. The tile appears automatically on all POS devices connected to that store 3. Each location's staff uses the same tile — no per-location configuration needed ### Location-specific reporting In **Dashboard**, review gift card activity across your store. Since all locations share the same Shopify store, all sales and redemptions roll up into a single analytics view. Use Shopify's built-in location reports (Admin → Analytics) to break down activity by POS location. ### Physical card inventory per location If you're using physical gift cards, track which card batches are at which location. When you run a monthly reconciliation, do it per location. See [[physical-card-inventory|Managing Physical Gift Card Inventory]] for the full process. ## Scenario B — Separate Shopify store per location (or per region) Each location has its own Shopify store. By default, a gift card from Store A doesn't work at Store B. GiftCard Hero's [[multistore|Multi-Store]] feature solves this. ### Setting up cross-store gift cards 1. Designate one store as the primary (usually your main/largest location) 2. Install GiftCard Hero on all stores 3. Connect them in **Multi-Store → Manage Network** Once connected, a card issued at any store in the network works at all other stores. ### Considerations for multi-store - **Separate subscriptions** — each store needs its own GiftCard Hero subscription - **Currency** — if locations operate in different currencies, configure exchange rate handling in Multi-Store settings - **Analytics** — each store's dashboard shows its own activity; there's no unified cross-store dashboard (you'd need to export and combine manually) - **POS** — POS on each store's devices works independently; cross-store balance resolution happens transparently ### When cards are issued and where For consistent customer experience, decide: - **Central issuance** — all gift cards are issued from the primary store, distributed to locations - **Local issuance** — each location issues its own cards; they work everywhere via the network Central issuance is simpler for accounting; local issuance is more operationally flexible. ## Staff training for multi-location For POS staff at any location: 1. **Checking a balance** — same process everywhere; the system fetches the balance from wherever the card was issued 2. **Accepting a card** — no different from normal; Shopify POS handles gift card redemption natively 3. **Issuing a new card** — issued in the current store; valid everywhere via the network 4. **"Card not found" error** — tell the customer to contact head office; don't assume the card is invalid ## Franchise model If you operate as a franchise (locations are independently owned), consider: - Who "owns" the gift card liability when a card is issued in one franchise and redeemed in another - How to settle cross-location redemptions (e.g., monthly reconciliation and transfer) - Whether to restrict certain locations from issuing vs. only redeeming GiftCard Hero doesn't handle financial settlement between franchise locations — that's an accounting/legal matter between you and your franchisees. --- ## Managing Physical Gift Card Inventory Source: https://docs.syncu.be/giftcard-hero/use-cases/physical-card-inventory/ # Managing Physical Gift Card Inventory This guide covers the end-to-end operational workflow for retailers who sell physical gift cards in-store. ## The physical gift card lifecycle ``` Order cards from manufacturer ↓ Receive code file from manufacturer ↓ Import codes into GiftCard Hero ↓ Cards arrive at store locations ↓ Customer purchases card at POS → card is activated ↓ Customer uses card at checkout or POS ↓ Balance depletes → card fully redeemed ``` ## Step 1 — Ordering cards from a manufacturer Most physical gift card manufacturers provide: - Pre-printed cards with unique codes (magnetic stripe, barcode, or QR code) - A CSV or Excel file with all the codes and corresponding serial numbers - Optional: an activation service (they load the balance, you don't need to) If using GiftCard Hero for activation, order "unactivated" cards — the balance is $0 until you sell and activate them. This is more secure because a stolen unactivated card is worthless. Popular physical gift card manufacturers include CPI Card Group, Stored Value Systems, and many regional providers. ## Step 2 — Importing codes When your code file arrives from the manufacturer: 1. Review the file — confirm it has the expected number of unique codes 2. Go to **eGift Cards → Physical Cards → Import Codes** 3. Upload the CSV 4. Map the code column 5. Set **Activation mode** to **Activate on sale** (for unactivated cards) or **Pre-activated** (if the manufacturer pre-loaded balances) 6. Set the denomination (e.g., $50 per card — or leave blank if cards have variable load amounts) 7. Click **Import** ### Handling multiple denominations in one shipment If your shipment includes cards of different values (e.g., 500 × $25 cards and 300 × $50 cards), import them separately with the correct denomination setting for each batch. ## Step 3 — Distributing to store locations GiftCard Hero doesn't handle physical logistics — that's your job. Once codes are imported, assign cards to locations using your usual inventory process. Keep a record of which codes went to which location (this helps with loss prevention). ## Step 4 — Activating at POS When a customer buys a physical gift card at the register: 1. Staff scans the barcode/QR on the card using the POS scanner or types the code manually 2. In Shopify POS, the card appears as "unactivated" — staff confirms the sale 3. Shopify charges the customer (e.g., $50) 4. GiftCard Hero activates the card and loads $50 onto the code 5. The card is now a live Shopify gift card the customer can use anywhere The activation happens automatically when the POS sale is processed — staff don't need extra steps. ## Step 5 — Tracking stock levels GiftCard Hero tracks: - **Total imported codes** — all codes ever imported from this manufacturer batch - **Activated** — codes that have been sold and activated - **Unactivated** — codes not yet sold (available stock) - **Redeemed** — codes where balance has reached $0 Use the **Physical Cards** page as your inventory report. Export to CSV for reconciliation with your physical stock count. ### Stock alerts Set a **Low stock alert** in Physical Cards settings — you'll receive an email when unactivated codes drop below a threshold (e.g., 50 remaining). This gives you time to reorder before running out. ## Loss prevention Physical gift cards are a theft target. Mitigations: - Use **activate on sale** mode — stolen unactivated cards are worthless - Keep unactivated card stock locked up or behind the counter - Audit your inventory monthly — compare physical count with GiftCard Hero's "unactivated" count - If cards go missing, they can be individually disabled in GiftCard Hero before being activated ## Reconciliation Monthly reconciliation: 1. Export **Physical Cards → Unactivated** codes to CSV 2. Count physical cards in each location 3. Any discrepancy between the system count and physical count warrants investigation Document and report shrinkage per your internal policy. --- ## Refunds as Gift Cards Source: https://docs.syncu.be/giftcard-hero/use-cases/refunds-as-gift-cards/ # Refunds as Gift Cards Instead of processing a cash refund (which returns money to the customer and leaves you with nothing), you can refund to a gift card. The customer gets their money back in a form they can spend at your store — and you retain the revenue. ## Why refund to a gift card? - **You keep the revenue** — the money stays in your store, not returned to a bank account - **Sales lift** — customers with store credit tend to spend more than the credit value (see [[dashboard|Sales Lift]] in analytics) - **Better for no-fault returns** — when a product is returned because it didn't suit the customer (not defective), store credit is often acceptable - **Faster than cash refunds** — issuing a gift card is immediate; bank refunds take 3–10 days > **Note:** In some regions, consumers have a legal right to a cash refund in certain circumstances (e.g., defective products). Always comply with local consumer protection law. Store credit refunds are generally safest to offer as an option rather than a requirement. ## Setting up refund-to-gift-card There's no specific "refund mode" to enable — you just issue a gift card for the refund amount and don't process the original payment method refund. ### From the admin (online returns) 1. Determine the refund amount 2. Go to **GiftCard Hero → eGift Cards → Issue Gift Card** 3. Enter the customer's email, the refund amount, and a message like "Your refund from Order #1234 — ready to use at checkout" 4. Click **Send** 5. In Shopify Admin, mark the order as refunded without processing a payment refund (use the "Do not restock" and "Refund manually" options) Or if you prefer, add a note to the order: "Refunded via gift card — GiftCard Hero card ID: ..." ### From POS (in-store returns) 1. Find the order in Shopify POS 2. Tap **Refund** 3. Select the items to return 4. Under **Refund method**, choose **Gift Card** 5. Choose to load onto an existing card (if the customer has one) or issue a new card See [[pos-integration|POS Integration → Refunding to a gift card]] for the full POS workflow. ## Making it a policy If you want to offer refund-to-gift-card as a standard option: 1. **Update your refund policy** to mention that refunds may be issued as store credit in certain cases 2. **Train staff** on the POS workflow 3. **Offer an incentive** — e.g., "Refund to gift card and get 10% extra" (a $50 refund becomes a $55 gift card) — this increases acceptance rates significantly 4. **Be transparent** — don't force it on customers, offer it as a choice alongside the standard refund ## Handling exchanges For exchanges (customer wants a different size, color, or item): 1. Issue a gift card for the return value 2. Customer uses the gift card to purchase the replacement item This avoids a refund/re-charge cycle and is especially clean for online returns where the customer ships the item back and you want to let them shop again easily. ## Tracking refund-to-gift-card revenue In **Dashboard**, you can see the total value of gift cards currently outstanding. Cards issued as refunds add to this outstanding balance. When they're redeemed, they convert from liability to revenue. To specifically track refund-related cards, use a dedicated gift card type called something like "Store Credit / Refund" — then filter analytics by that type. --- ## GiftCard Hero — FAQ Source: https://docs.syncu.be/giftcard-hero/faq/app-questions/ # GiftCard Hero — Frequently Asked Questions ## General ### Does GiftCard Hero replace Shopify's gift card system? No. GiftCard Hero builds on top of Shopify's native gift card system. All cards created by the app are real Shopify gift cards — they appear in your Shopify Admin and work in Shopify's standard checkout and POS. ### What happens if I uninstall GiftCard Hero? - All issued gift cards remain valid (they are native Shopify gift cards) - The balance check widget is removed from your storefront - The gift card delivery email reverts to Shopify's default email - Your data is retained for 30 days in case you reinstall, then permanently deleted ### Can I use GiftCard Hero on multiple Shopify stores? Yes, but each store requires a separate GiftCard Hero subscription. If you want cards to work across stores, use the [[multistore|Multi-Store]] feature to link them. ### Is GiftCard Hero GDPR compliant? GiftCard Hero processes customer data (email addresses, names, transaction history) necessary to issue and track gift cards. We comply with GDPR requirements, including data subject access requests and the right to deletion. See our Privacy Policy for full details. ## Gift Cards ### How quickly is the gift card email delivered? Gift card emails are sent immediately after the order is confirmed (or on the scheduled date if a future delivery date was selected). Delivery to the recipient's inbox typically takes a few seconds to a few minutes. If an email doesn't arrive within 15 minutes, ask the recipient to check their spam folder. ### Can I customize the gift card code format? No — gift card codes are generated by Shopify and use Shopify's standard 16-character format. You cannot set custom code patterns. ### Can I set different expiry dates for different card types? Yes. Expiry is configured per gift card type. One type can have no expiry, another can expire after 2 years. ### Can customers send a gift card with a future delivery date? Yes. During checkout, buyers can select a delivery date in the future. The email is sent on that date, not at purchase time. You can enable or disable this option per gift card type. ### What happens if the recipient's email address is wrong? The email bounces. You'll see the delivery failure in the gift card's record. Open the card in GiftCard Hero, correct the email address, and click **Resend Email**. ### Can a gift card be used to pay for shipping? Yes — gift cards apply to the entire order total, including shipping. ### Can I issue a gift card in a currency different from my store's currency? No. Gift cards are always in your store's currency. If you serve customers in multiple currencies, each store (currency) would need its own gift card program. ## Bulk Operations ### How many gift cards can I generate at once? Up to 10,000 per bulk job. For larger quantities, split into multiple jobs. ### How long does a bulk job take? Roughly 500 cards/minute for Generate jobs, 200 emails/minute for Send jobs. A 10,000-card Generate job takes about 20 minutes; a 10,000-recipient Send job takes about 50 minutes. You don't need to keep the browser open — jobs run in the background. ### What happens if some rows in my bulk send fail? Failed rows are listed in the results CSV with an error message. You can fix the issues and re-run only the failed rows by uploading a corrected CSV. ### Can I pause or cancel a bulk job? You can cancel a job while it's running. Already-issued cards are not revoked. Partially completed jobs show in the results with the cards that were created before cancellation. ## Analytics ### Why is my redemption rate lower than expected? Common reasons: - Cards were recently issued and haven't been used yet (check the redemption lag chart) - Gift card emails are going to spam - Denominations don't match your average order value (e.g., a $200 card in a store with $30 AOV) - Consider enabling [[reminders|Unused Balance Reminders]] ### What is "sales lift"? Sales lift is the extra revenue generated because gift card customers spend more than their card value. If a customer has a $50 card and spends $78, the lift is $28. This measures the real economic value of your gift card program beyond the face value of cards sold. See [[dashboard|Dashboard]] for details. ## Billing ### How is billing calculated? GiftCard Hero charges a monthly subscription fee based on your plan tier. Plans differ by the number of gift cards you can issue per month and access to advanced features. Visit the Plans page in the app for current pricing. ### Is there a free trial? Yes — new installations get a free trial period. The trial length is shown during installation. ### What happens if I exceed my plan's gift card limit? You'll receive a notification when you're approaching your limit. If you exceed it, additional card issuance is paused until the next billing cycle or you upgrade your plan. ## Integrations ### Does GiftCard Hero integrate with my email marketing platform? Not directly, but you can use webhooks to trigger actions in external platforms when gift card events occur. Common integrations: - Klaviyo: trigger a flow when a card is issued or a reminder is sent - Mailchimp: add buyers to a "gift card purchaser" segment - Custom: use the webhook API to send events to any platform ### Does GiftCard Hero work with Shopify Markets? Yes. GiftCard Hero works with Shopify Markets. Gift cards are issued in your store's primary currency. Cross-market redemption depends on your Shopify Markets currency settings. ### Can I use GiftCard Hero with a headless Shopify storefront? Yes, via the API. GiftCard Hero provides a REST API and Storefront API compatibility for headless implementations. See [[developer-tools|Developer Tools]] for API access. --- ## Troubleshooting Source: https://docs.syncu.be/giftcard-hero/faq/troubleshooting/ # 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 `` 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}}` --- ## Missing Gift Cards If a customer says they haven't received their gift card, follow these steps. ### 1. Confirm the gift card was issued In **Shopify admin → Products → Gift cards**, search by customer name or email. Verify the code exists and is active. ### 2. Check delivery status in Gift Card Hero Go to **Apps → Gift Card Hero → Analytics → Queue Report**. Search by recipient email or order number. - **Scheduled** — gift card set to send in the future (check delivery date) - **Sent** — email was delivered - **Failed** — delivery issue occurred ### 3. Resend or update If status is "Sent" but customer hasn't received it: - Ask customer to check Spam, Promotions, or Updates folders - Confirm email address is correct - To change: click email link in Queue Report → update email/date → Save → Resend ### 4. Check for email issues - Custom email domain: verify SPF/DKIM records - Multiple customers affected: contact email provider or Shopify Support ### 5. Issue a replacement If card can't be resent: issue a new gift card in **Shopify admin → Products → Gift cards → Issue gift card** and email the code manually. > **Tip:** Most missing gift cards are caused by incorrect email addresses or spam filtering. --- ## 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 [[multistore|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. --- ## Troubleshooting Missing Gift Cards Source: https://docs.syncu.be/giftcard-hero/faq/missing-gift-cards/ # Troubleshooting Missing Gift Cards If a customer says they haven't received their gift card email, follow these steps to investigate and resolve the issue. --- ## 1. Confirm the gift card was issued - In **Shopify admin**, go to **Products → Gift cards** - Search by the customer's name or email - Make sure the gift card code exists and is active --- ## 2. Check the delivery status in Gift Card Hero 1. Go to **Apps → Gift Card Hero → Analytics → Queue Report** 2. Search for the gift card by recipient email or order number Review its status: - **Scheduled** — the gift card is set to send in the future (check delivery date) - **Sent** — the email was sent to the customer - **Failed** — there was an issue delivering the email --- ## 3. Resend or update the gift card If the status is **Sent** but the customer hasn't received it: - Ask the customer to check their **Spam**, **Promotions**, or **Updates** folders - Confirm the email address is correct If the address is wrong or needs to be changed: 1. In **Queue Report**, click the **email link** for that gift card 2. Update the recipient's email and/or delivery date 3. Click **Save** and **Resend gift card** --- ## 4. Check for email deliverability issues - If you use a custom email domain, make sure your domain's SPF/DKIM records are set correctly so Shopify emails aren't marked as spam - If multiple customers are reporting missing gift cards, contact your email provider or Shopify Support to check for delivery problems --- ## 5. Issue a replacement if needed If the gift card can't be resent for any reason: - Issue a **new gift card** in Shopify and email the code manually to the customer - In Shopify admin: **Products → Gift cards → Issue gift card** --- > **Tip:** Most missing gift cards are caused by incorrect email addresses or the email landing in the spam folder. Always verify these two before issuing a replacement. --- ## Gift Card Basics in Shopify — FAQ Source: https://docs.syncu.be/giftcard-hero/faq/shopify-basics/ # Gift Card Basics in Shopify — FAQ ## What Shopify plan do I need? Gift cards are available on **Shopify, Advanced Shopify, and Shopify Plus** plans. The Basic Shopify plan does not include gift card functionality. If you're on Basic, you'll need to upgrade your plan before using GiftCard Hero. ## Can customers use a gift card with a discount code? Yes. Shopify allows a gift card and a discount code to be used in the same order. The discount applies first (reducing the item prices), and then the gift card is applied as payment to the reduced total. ## Can customers use more than one gift card per order? Yes. Shopify allows up to 10 gift cards to be applied to a single order. ## Can a customer use a gift card to buy another gift card? No. Shopify prevents gift cards from being used to purchase other gift cards. This is a Shopify platform restriction, not a GiftCard Hero limitation. ## Do gift cards expire? That depends on your settings. Shopify allows you to set an expiry date on gift cards. GiftCard Hero lets you configure expiry per gift card type. **Important:** Many jurisdictions regulate gift card expiry: - **USA:** Most states require a minimum 5-year expiry. California, Florida, and others ban expiry entirely. - **Canada:** Gift cards cannot expire under federal law (with narrow exceptions). - **UK:** No federal ban, but consumer protection principles apply. - **Australia:** Minimum 3-year expiry under Australian Consumer Law. - **EU:** No harmonized regulation; varies by member state. Always consult a lawyer in your jurisdiction before setting expiry dates. ## Are gift cards taxed? In most jurisdictions, gift card **purchases** are not subject to sales tax — you're selling a future payment method, not a product. Sales tax is collected when the gift card is **redeemed** to buy taxable goods. Shopify handles this automatically. The gift card sale appears as a liability in your Shopify financial reports, which is offset when the card is used. Tax rules vary by country and state — consult your accountant. ## What happens to the money from unused gift cards? Unredeemed gift card balances are a liability on your books — you owe the holder that value. In some US states, unclaimed gift card balances must be escheated (turned over to the state) after a certain period (usually 3–5 years). This is called **gift card breakage**. Consult your accountant about how to handle breakage in your jurisdiction. ## Can I refund to a gift card instead of the original payment method? In most cases, yes — this is a policy decision, not a technical one. You issue a gift card for the refund amount instead of processing the refund to the original payment method. Be aware that: - Some consumer protection laws require cash refunds for defective products - Store credit refunds are generally fine for returns where the product is not defective - You should disclose your store credit refund policy clearly See [[refunds-as-gift-cards|Refunds as Gift Cards]] for the operational guide. ## Why can't I see gift cards in my Shopify Admin? Gift cards appear in **Shopify Admin → Gift Cards** only on eligible plans. If you're on Basic, this section won't exist. If you're on an eligible plan and still can't see it, contact Shopify support — it may be a plan activation issue. ## Do gift cards work in Shopify POS natively? Yes, Shopify POS natively supports gift card redemption. A customer can present their code and staff can apply it to the POS transaction. However, issuing new cards, checking balances, and processing refunds to gift cards at POS require GiftCard Hero's POS extension. ## What is the format of a Shopify gift card code? Shopify gift card codes are typically 16 alphanumeric characters (letters and numbers), displayed in groups of 4: `ABCD-EFGH-IJKL-MNOP`. Codes are case-insensitive. When a customer types their code at checkout, they can include or omit the dashes — both formats work. ## Can I import gift card codes I generated elsewhere? Yes, via [[physical-cards|Physical Gift Cards]] — you can import codes from any source (a manufacturer, a previous system, or codes you generated yourself). Each imported code becomes a live Shopify gift card with the balance you set. ## What happens to gift cards if I switch from GiftCard Hero to another app? All gift cards created by GiftCard Hero are native Shopify gift cards. They remain valid regardless of which app you use or whether you uninstall GiftCard Hero. The codes will work at your store's checkout forever (unless you disable them in Shopify Admin or they expire).